Keep a disaster-recovery copy, step by step
A disaster-recovery copy keeps a second copy of a whole bucket in another location, so that your files survive the loss of a region. It is on for one bucket at a time, takes a few clicks, and then looks after itself. The reference is in Storage.
Deletes follow. Deleting a file from your bucket deletes it from the copy too. A disaster-recovery copy protects you from losing a region, not from deleting your own files. The copy is read-only: you can't read or write it yourself.
You need: the Growth or Enterprise plan, an active bucket, an admin key to turn the copy on or off (any key can read its status), and one of plycdn's server packages (ASP.NET Core, Node.js or Python) or the API.
1What you get
- The whole bucket is copied, including every file already in it and every file you add later. New files usually reach the copy within minutes. Copying the files already in a large bucket takes longer; the status shows how far it has got.
- One copy location per bucket. It has to be another location from the bucket's own. To use a different one, turn the copy off and on again.
- During a regional outage your files are safe in the copy, and our team can switch the bucket to its copy: contact us. While a switch is in progress, uploads and deletes to that bucket wait (they answer a retryable error) and viewing keeps working. We don't promise automatic delivery from the copy.
- Strict residency is respected: a strict bucket can only keep its copy in another location in the same country.
2What it costs
Two lines on your statement, both on the plans and prices page:
- DR copy storage, in GB-months: the bucket's own billed size each day, at the storage price of the copy's location. The bucket and its copy match on your statement.
- DR data transfer: ₹3 per GB (or $0.04 per GB), counted for every GB sent to the copy. The first copy of files already in the bucket is billed the same way, once, when you turn the copy on.
Turning the copy off stops it and deletes the copy; its billing stops when the copy is gone, normally the same day.
3Turn it on
In the dashboard: Storage → Storage buckets → the bucket → Disaster recovery → Turn on, choose the location for the copy and confirm.
From your code:
PUT /api/content/v1/buckets/{bucketId}/replication {"region": "hyderabad"}
The locations you can choose are each region's drTargets in GET /regions. The call answers at once while the copy
starts.
ASP.NET Core
var copy = await storage.EnableBucketReplicationAsync(organizationId, bucketId, "hyderabad");
Console.WriteLine(quot;{copy.Region}: {copy.State}");
Node.js
const copy = await storage.enableBucketReplication(organizationId, bucketId, 'hyderabad');
console.log(copy.region, copy.state);
Python
copy = storage.enable_bucket_replication(organization_id, bucket_id, "hyderabad")
print(copy["region"], copy["state"])
4Check that it works
In the dashboard the bucket's Disaster recovery panel shows a status:
| Status | Meaning |
|---|---|
| Preparing | The copy is being set up |
| Copying existing files: x of y | Files already in the bucket are being copied. y is an estimate until the end |
| Protected | The copy matches the bucket: "Copy up to date as of …" |
| Needs attention | Something stopped the copy; the panel says why. Contact us if it stays |
| Turning off | The copy is being removed |
| Switching | Our team is moving the bucket to its copy |
From code, GET /buckets/{bucketId}/replication answers state (preparing, copying, active for Protected,
attention, stopping, switching or off), region, reason (when it needs attention), upToDateAt,
copiedObjects, totalObjects, billedGb and transferGb for this month. The same replication summary is on the
bucket itself.
ASP.NET Core
var status = await storage.GetBucketReplicationAsync(organizationId, bucketId);
Console.WriteLine(quot;{status.State}, up to date as of {status.UpToDateAt}");
Node.js
const status = await storage.getBucketReplication(organizationId, bucketId);
console.log(status.state, status.upToDateAt);
Python
status = storage.get_bucket_replication(organization_id, bucket_id)
print(status["state"], status.get("upToDateAt"))
You are protected when the state is active and upToDateAt is recent.
5Turn it off
In the dashboard: Storage → Storage buckets → the bucket → Disaster recovery → Turn off. The confirmation names the location and the size of the copy that will be deleted. The bucket itself is untouched.
DELETE /api/content/v1/buckets/{bucketId}/replication
The answer is stopping while the copy is removed. Turning off a bucket that has no copy is not an error: it answers 200 with state off.
ASP.NET Core await storage.DisableBucketReplicationAsync(organizationId, bucketId);
Node.js await storage.disableBucketReplication(organizationId, bucketId);
Python storage.disable_bucket_replication(organization_id, bucket_id)
6Errors and fixes
| Code | What it means | What to do |
|---|---|---|
replication_not_in_plan (403) |
Your plan doesn't include disaster-recovery copies | Move to Growth or Enterprise, or contact us |
admin_key_required (403) |
Turning the copy on or off needs an admin key | Use an admin key |
bucket_not_active (409) |
The bucket is still being created, or is deleting | Wait until it is active and try again |
replication_region_not_available (400) |
That location can't hold a copy | Use one of the drTargets of the bucket's location in GET /regions |
replication_same_region (400) |
The copy would be in the bucket's own location | Choose a different location |
replication_residency_conflict (400) |
A strict-residency bucket's copy must stay in its country | Choose another location in the same country |
replication_already_on (409) |
The bucket already has a copy | Read its status; to change the location, turn it off, then on |
replication_busy (409) |
The copy is changing state (starting, stopping or switching) | Wait and retry. Retryable |
replication_not_found (404) |
The copy changed while you were acting | Rare: the copy changed while you were acting. Read its status and try again |
feature_not_available (404) |
Copies are not switched on for your account yet | Contact us |
7Where to go next
- Choose where a bucket lives in the first place: Choose where files live.
- Reference: Storage and Buckets in the API.