Add documentation for new backup and restore cloud API endpoints #20012

jhlodin · 2025-07-28T19:18:46Z

Fixes DOC-11599

Add task-oriented guidance to our docs around using the cloud API to:

View managed backups
Restore cluster objects
Restore database objects
Restore table objects
View restore operations on a cluster

Opted to break out our existing include(s) for human readability due to different functionality between Cloud plans

github-actions · 2025-07-28T19:19:08Z

Files changed:

src/current/_includes/cockroachcloud/backups/cloud-api-backup-settings.md:

src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md:

src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md:

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md:

src/current/cockroachcloud/cloud-api.md
src/current/cockroachcloud/managed-backups-advanced.md
src/current/cockroachcloud/managed-backups-basic.md
src/current/cockroachcloud/managed-backups.md

netlify · 2025-07-28T19:19:37Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`e675fbf`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/6890d8fda82f490008f2ab5b

netlify · 2025-07-28T19:19:47Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`8dc9fd2`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/6887cd19ea6d380007fff9a2

netlify · 2025-07-28T19:20:09Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`e675fbf`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/6890d8fd28c6af0008bb95c3

netlify · 2025-07-28T19:27:27Z

❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →

Name	Link
🔨 Latest commit	`8dc9fd2`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/6887cd19addfc8000839bcc2

netlify · 2025-07-28T19:37:44Z

❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →

Name	Link
🔨 Latest commit	`4610218`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/6887cd4d07089d000819c983

netlify · 2025-07-28T19:47:17Z

❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →

Name	Link
🔨 Latest commit	`d662973`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/6887d056581dab00085ffc4e

netlify · 2025-07-28T19:49:36Z

✅ Netlify Preview

Name	Link
🔨 Latest commit	`e675fbf`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/6890d8fd416a890008543288
😎 Deploy Preview	https://deploy-preview-20012--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

florence-crl

Would you be able to fix the first link for "Managed backups" in the following section? https://deploy-preview-20012--cockroachdb-docs.netlify.app/docs/cockroachcloud/backup-and-restore-overview#managed-backups
It currently points to the same page. Please make it point to https://deploy-preview-20012--cockroachdb-docs.netlify.app/docs/cockroachcloud/managed-backups
I just realized that it is in an include file as the intro paragraph for the managed-backup pages.

lgtm pending suggestions (mostly nits about verb tense)

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md

src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md

alicia-l2

lgtm - left a few notes!

alicia-l2 · 2025-07-29T19:38:58Z

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md

+  "status": "PENDING",
+  "created_at": "2025-07-25T16:45:14.064208710Z",
+  "type": "CLUSTER",
+  "completion_percent": 0


nit - can we say 100 as that would be 100% completed aka successful?

@linhcrl I believe on Intrusion we return a float64 (i.e. 1 instead of 100). Does Console update this to a percentage value?

nope, we keep it a float between 0 and 1

This should be call fraction_completed

we purposely renamed it for the CC API

This should be read as the JSON returned immediately to the POST request, wouldn't it show the lowest completion percent?

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md

kev-cao · 2025-07-29T20:31:19Z

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md

+  "status": "PENDING",
+  "created_at": "2025-07-25T16:45:14.064208710Z",
+  "type": "CLUSTER",
+  "completion_percent": 0


@linhcrl I believe on Intrusion we return a float64 (i.e. 1 instead of 100). Does Console update this to a percentage value?

linhcrl

Left some comments. Let me know if you have any questions. Thanks for putting this together!

src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md

linhcrl · 2025-07-30T14:38:41Z

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md

+  "status": "PENDING",
+  "created_at": "2025-07-25T16:45:14.064208710Z",
+  "type": "CLUSTER",
+  "completion_percent": 0


nope, we keep it a float between 0 and 1

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md

edwardguo-crl · 2025-07-30T16:46:48Z

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md

+~~~
+{% endif %}
+
+You can specify additional options for the restore operation in the `restore_opts` object. For more information, see the [API endpoint documentation](https://www.cockroachlabs.com/docs/api/cloud/v1#get-/api/v1/clusters/-cluster_id-/restores-config).


Where is this document?

I put this in as a placeholder for the actual API reference docs URL. If it'll be different when published, please let me know and I can update.

Sounds good, please tag me when the param document is available. Thanks!

It should be part of the proto? Since this link goes out to the API documentation, it's not going to docs that I'm writing.

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md

jhlodin force-pushed the jl/doc-11599 branch from 8dc9fd2 to 4610218 Compare July 28, 2025 19:19

jhlodin requested a review from mikeCRL July 28, 2025 19:20

jhlodin force-pushed the jl/doc-11599 branch from ceab10e to 20e636b Compare July 28, 2025 20:36

florence-crl approved these changes Jul 29, 2025

View reviewed changes

alicia-l2 reviewed Jul 29, 2025

View reviewed changes

kev-cao reviewed Jul 29, 2025

View reviewed changes

linhcrl reviewed Jul 30, 2025

View reviewed changes

edwardguo-crl reviewed Jul 30, 2025

View reviewed changes

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md Show resolved Hide resolved

edwardguo-crl reviewed Jul 30, 2025

View reviewed changes

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md Outdated Show resolved Hide resolved

edwardguo-crl reviewed Jul 30, 2025

View reviewed changes

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md Outdated Show resolved Hide resolved

jhlodin force-pushed the jl/doc-11599 branch 3 times, most recently from 52ac555 to f99a427 Compare July 31, 2025 02:18

edwardguo-crl reviewed Aug 3, 2025

View reviewed changes

src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md Show resolved Hide resolved

jhlodin added 7 commits August 4, 2025 11:59

Add documentation for new backup and restore cloud API endpoints

0fac13f

Add cross-cluster restore operation examples

5fadc8e

Add missing view backups snippet

41b362e

Slight rewording

746b490

Corrections

6b1fef5

Address eng and PM comments

6a9a659

Adjust restore_opt to be advanced only

97a7101

Remove outdated cluster wipe warning

e675fbf

jhlodin force-pushed the jl/doc-11599 branch from 810aa09 to e675fbf Compare August 4, 2025 15:59

Add documentation for new backup and restore cloud API endpoints #20012

Are you sure you want to change the base?

Add documentation for new backup and restore cloud API endpoints #20012

Uh oh!

Conversation

jhlodin commented Jul 28, 2025 • edited by florence-crl Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Files changed:

Uh oh!

netlify bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Uh oh!

netlify bot commented Jul 28, 2025

✅ Deploy Preview for cockroachdb-api-docs canceled.

Uh oh!

netlify bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-api-docs canceled.

Uh oh!

netlify bot commented Jul 28, 2025

❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →

Uh oh!

netlify bot commented Jul 28, 2025

❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →

Uh oh!

netlify bot commented Jul 28, 2025

❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →

Uh oh!

netlify bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Netlify Preview

Uh oh!

florence-crl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alicia-l2 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

linhcrl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jhlodin commented Jul 28, 2025 •

edited by florence-crl

Loading

github-actions bot commented Jul 28, 2025 •

edited

Loading

netlify bot commented Jul 28, 2025 •

edited

Loading

netlify bot commented Jul 28, 2025 •

edited

Loading

netlify bot commented Jul 28, 2025 •

edited

Loading

jhlodin Jul 30, 2025 •

edited

Loading