Using Replication

Replication provides protection from regional outages, aids in disaster recovery efforts, and addresses data redundancy compliance requirements. Maintaining multiple copies of data in regional locations closer to user access can also reduce latency.

This topic describes Object Storage replication and provides details on how to replicate the objects in one bucket to another bucket in the same region or a different region.

About Object Storage Replication

Enabling Object Storage replication is as simple as creating a replication policy on the source bucket that identifies the region and the bucket to replicate to. After the replication policy is created, the destination bucket is read-only and updated only by replication from the source bucket. Objects uploaded to a source bucket after policy creation are asynchronously replicated to the destination bucket. Objects uploaded to a source bucket before policy creation are not replicated.

Replication overwrites any object in the destination bucket that has the same name as an object in the source bucket. A replicated object has the same name, metadata, ETag, and MD5 value as the object in the source bucket. The creation timestamp, modified timestamp, and archival state can be different, so these attributes are not replicated from the source.

Required IAM Policies

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy  written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment  you should work in.

If you're new to policies, see Getting Started with Policies and Common Policies.

Warning

Replication does not work if you do not authorize the Object Storage service to replicate objects on your behalf. See Service Permissions for more information.

User Permissions

You must have the required access to both the source and destination buckets when configuring replication. You must also have permissions to manage objects in the source and destination buckets.

For administrators:

  • You can create a policy that lets the specified IAM group manage Object Storage namespaces, buckets, and their associated objects in all compartments in the tenancy. For example, here is a simple user access policy that lets a StorageAdmins group do anything with the Object Storage service resources in the tenancy:

    Allow group StorageAdmins to manage object-family in tenancy
  • Alternatively, you can create policies that reduce the scope of access. For example, you can create the policies to let the StorageAdmins group manage buckets and objects in a compartment called ObjectStore in the tenancy:

    Allow group StorageAdmins to manage buckets in compartment ObjectStore
    Allow group StorageAdmins to manage objects in compartment ObjectStore

For more information about other alternatives for writing policies, see Details for Object Storage, Archive Storage, and Data Transfer.

Service Permissions

Because Object Storage is a regional service, you must authorize the Object Storage service for each region carrying out replication on your behalf. For example, you might authorize the Object Storage service in region US East (Ashburn) to manage objects on your behalf. Once you authorize the Object Storage service, you can replicate the objects in a bucket in US East (Ashburn) to a bucket in another region.

To determine the region identifier value of an Oracle Cloud Infrastructure region, see Regions and Availability Domains.

For administrators:

To enable replication, you must authorize the service to manage objects on your behalf:

  • For example, here is a service access policy that lets the Object Storage service do anything with the resources in the tenancy in the US West (Phoenix) region:

    Allow service objectstorage-us-phoenix-1 to manage object-family in tenancy
  • Alternatively, you can create policies that reduce the scope of access. For example, you can create a policy that lets the Object Storage service do anything with the resources in a compartment called ObjectStore in the US West (Phoenix) region:

    Allow service objectstorage-us-phoenix-1 to manage object-family in compartment ObjectStore
  • If you create more restrictive policies that grant individual permissions, BUCKET_READ, BUCKET_UPDATE, OBJECT_READ, OBJECT_INSPECT, OBJECT_CREATE, OBJECT_OVERWRITE, OBJECT_RESTORE, OBJECT_DELETE are required for replication.

Scope and Constraints

  • Replication policy creation does not automatically create a destination bucket. Create the destination bucket before creating the replication policy on the source bucket.
  • A source or destination bucket can be in the Standard (Object Storage) or Archive Storage tier.
  • Maximum of one replication policy per bucket.
  • Maximum of one destination for each replication source bucket.
  • A destination bucket cannot also be a replication source. Chained replication is not supported.
  • After the replication policy is created, the destination bucket is read-only and updated only by replication from the source bucket.

Interaction Between Replication and Other Object Storage Features

This section describes some key things you need to know about the interaction between replication and other Object Storage features.

Lifecycle Management

You can combine replication with Lifecycle Management policies that manage the archiving and deletion of objects. Lifecycle policies must, however, honor the read-only properties of the replication destination bucket. A lifecycle policy that deletes objects from the replication destination bucket does not work. Carefully review and test any combination replication and lifecycle policies that you implement.

Here are examples of combination policies that might benefit you:

  • You can create a lifecycle policy on the source that deletes objects with certain file extensions after a specified number of days. The result of that deletion would also be reflected in the replication destination.
  • You can create a lifecycle policy on the destination that archives objects after a specified number of days. If you do not need immediate access to those objects, you could benefit from reduced storage costs.

Server-Side Encryption Using Your Own Keys

Replication cannot replicate objects that have been encrypted with an SSE-C key. For more information, see Using Your Own Keys for Server-Side Encryption.

Stopping Replication

Stopping replication can be initiated from either the replication source or the destination.

  • To stop replication from the source, delete the replication policy. Deleting a replication policy is permanent. You cannot recover a deleted policy. If you want to replicate to that target destination again, create a new policy.
  • To stop replication from the destination, make the destination bucket writable again. When you make the bucket writable, the destination bucket no longer accepts replication requests from the source. Replication status on the source changes from active to a client error state. If you want this destination to again be the target replication destination, delete the policy on the source bucket and create a new policy.

Troubleshooting Replication

This topic provides troubleshooting solutions for issues you might encounter using replication.

Unable to create a replication policy on the source bucket

If creating a replication policy fails, the most likely cause is missing or incomplete IAM permissions. Policy creation requires:

  • User permissions that let you access both the source and destination buckets and let you manage the objects in those buckets.
  • Service permissions that authorize Object Storage itself to access both the source and destination bucket and their objects.

Review the existing policies that grant user and service permissions. For more information, see Required IAM Policies.

Policy is in error on the source bucket

If the policy status changes from active to error, check these items:

  • You intentionally or unintentionally stopped replication on the destination bucket. To once again replicate to this target bucket, delete the existing policy on the source bucket and create a new policy.
  • Ensure that your user permissions are still in place.
  • Ensure that the policies that authorize Object Storage access to the source and destination buckets and their objects are still in place.
  • You might have exceeded your storage limits on the destination bucket. If you are a Free Trial or Always Free customer, your storage is limited. Upgrade to paid account or delete your replication policy.
Unable to stop replication on the destination bucket and make the bucket writable

If stopping a replication policy fails, the most likely cause is missing or incomplete IAM permissions. Policy creation requires:

  • User permissions that let you access both the source and destination buckets and let you manage the objects in those buckets.
  • Service permissions that authorize Object Storage itself to access both the source and destination bucket and their objects.

Review the existing policies that grant user and service permissions. For more information, see Required IAM Policies.

Using the Console

To create a replication policy
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. Choose the compartment that contains the bucket you want to replicate from.

  4. Click the bucket name.

  5. Click Replication Policy under Resources to access the replication policy list.
  6. Click Create Policy.

  7. In the Create Policy dialog, enter the following:

    • Name: Required. The system generates a default policy name that reflects the current year, month, day, and time, for example replication-policy-20200129-2230. If you change this default to a different policy name, use letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.
    • Destination Region: Required. The Oracle Cloud Infrastructure region containing the destination bucket that you want to replicate to. Your tenancy must be subscribed to a region for you to replicate to that region.
    • Destination Bucket: The name of the destination bucket for replication. Specify an existing target bucket. Replication cannot automatically create the bucket.
  8. Click Create.

    After the policy is created, Replication: Source is added to Bucket Information. Objects uploaded to the source bucket after policy creation are asynchronously replicated to the destination bucket.

To view the source replication policy details
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the source replication bucket.
  4. Click the source replication bucket name.
  5. Click Replication Policy under Resources to access the replication policy list.
To view the destination replication policy details
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the destination replication bucket.
  4. Click the destination replication bucket name.
  5. Click Replication Policy under Resources to access the replication policy list.
To stop replication on the destination bucket and make the bucket writable

If you stop replication, the policy is removed from this destination bucket and cannot be recovered. The bucket reverts to a standard read/write bucket and is no longer a replication target.

  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct replication destination region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the destination replication bucket.
  4. Click the destination replication bucket name.
  5. Click Replication Policy under Resources to access the replication policy list.
  6. Click Stop Replication.
To delete the replication policy on the source bucket
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the destination replication bucket.
  4. Click the replication destination bucket name.
  5. Click Replication Policy under Resources to access the replication policy list.

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the Command Line Reference.

To create a replication policy
oci os replication create-replication-policy --namespace <object_storage_namespace> --bucket-name <source_bucket_name> --destination-region <destination_region_identifier> --destination-bucket <destination_bucket_name>

For example:

oci os replication create-replication-policy --namespace MyNamespace --bucket-name MySourceBucket --destination-region us-ashburn-1 --destination-bucket MyDestinationBucket --name MyReplicationPolicy
{
  "data": {
    "destination-bucket": "MyDestinationBucket",
    "destination-region": "us-ashburn-1",
    "id": "bacb8334-b191-4026-aa65-5e4f5165ae3e",
    "name": "MyReplicationPolicy",
    "status": "ACTIVE",
    "status-message": "The policy is active.",
    "time-created": "2020-02-06T16:44:10+00:00",
    "time-last-sync": "2020-02-06T16:44:20+00:00"
  }
}

Objects uploaded to the source bucket after policy creation are asynchronously replicated to the destination bucket.

To view the replication policy details
oci os replication get-replication-policy --namespace <object_storage_namespace> --bucket-name <source_bucket_name> --replication-id <replication_policy_identifier> 

For example:

oci os replication get-replication-policy --namespace MyNamespace --bucket-name MySourceBucket --replication-id bacb8334-b191-4026-aa65-5e4f5165ae3e
{
  "data": {
    "destination-bucket": "MyDestinationBucket",
    "destination-region": "us-ashburn-1",
    "id": "bacb8334-b191-4026-aa65-5e4f5165ae3e",
    "name": "MyReplicationPolicy",
    "status": "ACTIVE",
    "status-message": "The policy is active.",
    "time-created": "2020-02-06T16:44:10+00:00",
    "time-last-sync": "2020-02-06T16:49:40+00:00"
  }
}
To list replication policies
Note

There is currently a maximum of one replication policy per bucket.
oci os replication list-replication-policies --namespace <object_storage_namespace> --bucket-name <destination_bucket_name>

For example:

oci os replication list-replication-policies --namespace MyNamespace --bucket-name MySourceBucket
{
  "data": [
    {
      "destination-bucket": "MyDestinationBucket",
      "destination-region": "us-ashburn-1",
      "id": "bacb8334-b191-4026-aa65-5e4f5165ae3e",
      "name": "MyReplicationPolicy",
      "status": "ACTIVE",
      "status-message": "The policy is active.",
      "time-created": "2020-02-06T16:44:10+00:00",
      "time-last-sync": "2020-02-06T16:53:42+00:00"
    }
  ]
}
To list the replication source for a destination bucket
oci os replication list-replication-sources --namespace <object_storage_namespace> --bucket-name <destination_bucket_name> --region <destination_region_identifier>

For example:

oci os replication list-replication-sources --namespace MyNamespace --bucket-name MyDestinationBucket --region us-ashburn-1
{
  "data": [
    {
      "policy-name": "MyReplicationPolicy",
      "source-bucket": "MySourceBucket",
      "source-region": "us-phoenix-1"
    }
  ]
}
To stop replication on the destination bucket and make the bucket writable
oci os replication make-bucket-writable --namespace <object_storage_namespace> --bucket-name <destination_bucket_name> --region <destination_region_identifier>

For example:

oci os replication make-bucket-writable --namespace MyNamespace --bucket-name MyDestinationBucket --region us-ashburn-1

If the command is successful, you are returned to the prompt.

To delete the replication policy on the source bucket
oci os replication delete-replication-policy --namespace <object_storage_namespace> --bucket-name <source_bucket_name> --replication-id <replication_policy_identifier>

For example:

oci os replication delete-replication-policy --namespace MyNamespace --bucket-name MySourceBucket --replication-id bacb8334-b191-4026-aa65-5e4f5165ae3e

Are you sure you want to delete this resource? [y/N]: y

If the command is successful, you are returned to the prompt.