how to use go sdk v2 to implement cross-region replication for buckets - Object Storage Service

You can use data replication features to automatically synchronize objects and the operations performed on the objects, such as the creation, overwriting, and deletion of objects from a source bucket to a destination bucket. OSS provides two data replication features: cross-region replication (CRR) and same-region replication (SRR).

Notes

The sample code in this topic uses the China (Hangzhou) region ID, cn-hangzhou. By default, a public endpoint is used to access resources in a bucket. If you want to access resources in the bucket from other Alibaba Cloud services in the same region, use an internal endpoint. For more information about the regions and endpoints that OSS supports, see OSS regions and endpoints.
In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.
By default, an Alibaba Cloud account is granted data replication-related permissions. If you want to replicate data as a RAM user or using temporary access credentials provided by Security Token Service (STS), you must have the required permissions. For example:
- To enable data replication, you must have the oss:PutBucketReplication permission.
- To enable or disable replication time control (RTC), you must have the oss:PutBucketRtc permission.
- To view data replication rules, you must have the oss:GetBucketReplication permission.
- To view the destination regions to which data can be replicated, you must have the oss:GetBucketReplicationLocation permission.
- To view the progress of a data replication task, you must have the oss:GetBucketReplicationProgress permission.
- To disable data replication, you must have the oss:DeleteBucketReplication permission.

Sample code

Enable data replication

Important

Before you enable data replication, make sure that the source bucket and the destination bucket are unversioned or versioning-enabled.

The following code provides an example of how to enable data replication. The source and destination buckets may be located in the same region or different regions.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Define global variables.
var (
	region     string // Region in which the bucket is located.
	bucketName string // Name of the bucket.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	var (
		targetBucket   = "target bucket name" // Name of the destination bucket.
		targetLocation = "oss-cn-beijing"     // Region in which the destination bucket is located.
	)

	// Check whether the name of the bucket is specified.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// Check whether the region is specified.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSS client.
	client := oss.NewClient(cfg)

	// Create a request to enable data replication for the bucket.
	request := &oss.PutBucketReplicationRequest{
		Bucket: oss.Ptr(bucketName), // Name of the bucket.
		ReplicationConfiguration: &oss.ReplicationConfiguration{
			Rules: []oss.ReplicationRule{
				{
					RTC: &oss.ReplicationTimeControl{
						Status: oss.Ptr("enabled"), // Enable the RTC feature.
					},
					Destination: &oss.ReplicationDestination{
						Bucket:       oss.Ptr(targetBucket),   // Name of the destination bucket.
						Location:     oss.Ptr(targetLocation), // Region in which the destination bucket is located.
						TransferType: oss.TransferTypeOssAcc,  // Type of transfer.
					},
					HistoricalObjectReplication: oss.HistoricalObjectReplicationEnabled, // Enable the historical data replication feature.
				},
			},
		},
	}

	// Enable data replication.
	result, err := client.PutBucketReplication(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to put bucket replication %v", err)
	}

	// Display the result.
	log.Printf("put bucket replication result:%#v\n", result)
}

Query data replication rules

The following code provides an example of how to query the data replication rules of a bucket.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Define global variables.
var (
	region     string // Region in which the bucket is located.
	bucketName string // Name of the bucket.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the name of the bucket is specified.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// Check whether the region is specified.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSS client.
	client := oss.NewClient(cfg)

	// Create a request to query the data replication rules of the bucket.
	request := &oss.GetBucketReplicationRequest{
		Bucket: oss.Ptr(bucketName),
	}

	// Perform the query operation.
	getResult, err := client.GetBucketReplication(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to get bucket replication %v", err)
	}

	// Display the result.
	log.Printf("get bucket replication result:%#v\n", getResult)
}

Enable or disable the RTC feature

The following code provides an example of how to enable or disable the RTC feature for a CRR rule.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Define global variables.
var (
	region     string // Region in which the bucket is located.
	bucketName string // Name of the bucket.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	var (
		ruleId = "replication id"
	)

	// Check whether the name of the bucket is specified.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// Check whether the region is specified.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSS client.
	client := oss.NewClient(cfg)

	// Create a request to enable or disable the RTC feature.
	request := &oss.PutBucketRtcRequest{
		Bucket: oss.Ptr(bucketName),
		RtcConfiguration: &oss.RtcConfiguration{
			RTC: &oss.ReplicationTimeControl{
				Status: oss.Ptr("enabled"),
			},
			ID: oss.Ptr(ruleId), // Specify the ID of the replication rule.
		},
	}

	// Perform the operation to enable or disable the RTC feature.
	result, err := client.PutBucketRtc(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to put bucket rtc %v", err)
	}

	// Display the result.
	log.Printf("put bucket rtc result:%#v\n", result)
}

Query the regions to which data can be replicated

The following code provides an example of how to query the regions to which data can be replicated from a bucket.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Define global variables.
var (
	region     string // Region in which the bucket is located.
	bucketName string // Name of the bucket.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the name of the bucket is specified.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// Check whether the region is specified.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSS client.
	client := oss.NewClient(cfg)

	// Create a request to query the regions to which data in the source bucket can be replicated.
	request := &oss.GetBucketReplicationLocationRequest{
		Bucket: oss.Ptr(bucketName),
	}

	// Perform the query operation.
	result, err := client.GetBucketReplicationLocation(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to get bucket replication location %v", err)
	}

	// Display information about the regions.
	for _, location := range result.ReplicationLocation.Locations {
		log.Printf("Bucket Replication Location: %s", location)
	}

	// Display the region for which the RTC feature can be enabled.
	for _, rtcLocation := range result.ReplicationLocation.LocationRTCConstraint.Locations {
		log.Printf("Bucket Replication Location RTC Location: %s", rtcLocation)
	}
}

Query the progress of a data replication task

Note

You can query the progress of historical data replication tasks and incremental data replication tasks.

The progress of historical data replication tasks is expressed as a percentage. You can query the progress of historical data replication tasks only for buckets for which historical data replication is enabled.
The progress of incremental data replication tasks is expressed as a point in time. Data that is stored in the source bucket before the point in time is replicated.

The following code provides an example of how to query the progress of the data replication task that has a specific replication rule ID in a bucket.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Define global variables.
var (
	region     string // Region in which the bucket is located.
	bucketName string // Name of the bucket.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Specify the ID of the replication rule.
	var ruleId = "replication id"

	// Check whether the name of the bucket is specified.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// Check whether the region is specified.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSS client.
	client := oss.NewClient(cfg)

	// Create a request to query the progress of the data replication task.
	request := &oss.GetBucketReplicationProgressRequest{
		Bucket: oss.Ptr(bucketName),
		RuleId: oss.Ptr(ruleId), // Specify the ID of the replication rule.
	}

	// Perform the query operation.
	result, err := client.GetBucketReplicationProgress(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to get bucket replication progress %v", err)
	}

	// Display the progress of the data replication task.
	for _, repProgressRule := range result.ReplicationProgress.Rules {
		log.Printf("Rule Id: %s", repProgressRule.ID)
		log.Printf("Status: %s", repProgressRule.Status)
		log.Printf("Replication Progress Rule Destination Bucket: %s", *repProgressRule.Destination.Bucket)
		log.Printf("Replication Progress Rule Destination Location: %s", *repProgressRule.Destination.Location)
		log.Printf("Replication Progress Rule Destination TransferType: %v", repProgressRule.Destination.TransferType)
		log.Printf("Replication Progress Rule Historical Object Replication: %s", *repProgressRule.HistoricalObjectReplication)
	}
}

Disable data replication

You can delete the replication rule that is configured for the specified source bucket to disable data replication for the bucket.

The following code provides an example of how to delete the replication rule that has a specific ID.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Define global variables.
var (
	region     string // Region in which the bucket is located.
	bucketName string // Name of the bucket.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Specify the ID of the replication rule.
	var ruleId = "replication id"

	// Check whether the name of the bucket is specified.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// Check whether the region is specified.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSS client.
	client := oss.NewClient(cfg)

	// Create a request to delete the data replication rule configured for the bucket.
	request := &oss.DeleteBucketReplicationRequest{
		Bucket: oss.Ptr(bucketName), // Name of the bucket.
		ReplicationRules: &oss.ReplicationRules{
			IDs: []string{ruleId}, // List of replication rule IDs.
		},
	}

	// Perform the operation to delete the data replication rule.
	result, err := client.DeleteBucketReplication(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to delete bucket replication %v", err)
	}

	// Display the result.
	log.Printf("delete bucket replication result:%#v\n", result)
}

References

For more information about the API operation that you can call to enable data replication, see PutBucketReplication.
For more information about the API operation for enabling or disabling the RTC feature for existing CRR rules, see PutBucketRTC.
For more information about the API operation for querying data replication rules, see GetBucketReplication.
For more information about the API operation for querying regions to which data can be replicated, see GetBucketReplicationLocation.
For more information about the API operation for querying the progress of a data replication task, see GetBucketReplicationProgress.
For more information about the API operation for disabling data replication, see DeleteBucketReplication.