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.

TODO:

Update release note date to the actual release date

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
src/current/v25.3/cockroachdb-feature-availability.md

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

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`e001657`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/689a6588e817b8000817b830

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	`e001657`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/689a65887eca620007fc954f

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	`e001657`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/689a6588f28be90008e3feda
😎 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

jhlodin · 2025-08-05T20:05:17Z

@laurenbarker @alicia-l2 From the sync, open questions for the docs are:

Do we need to add a "do not hit this endpoint more than X" note to listBackups?
Are we launching this in preview or GA as originally planned?
Do we need to yank listBackups out of this so we can ship restore ASAP?

Also I added a draft release note, PTAL. Date to be updated whenever we release.

src/current/releases/cloud.md

alicia-l2 · 2025-08-06T18:27:51Z

@laurenbarker @alicia-l2 From the sync, open questions for the docs are:

Do we need to add a "do not hit this endpoint more than X" note to listBackups?

Are we launching this in preview or GA as originally planned?

Do we need to yank listBackups out of this so we can ship restore ASAP?

Also I added a draft release note, PTAL. Date to be updated whenever we release.

No, let's not add that note.
We are launching in Limited Access
No, we don't need to yank Listbackups out.

reviewed release note as well, had a small nit.

Not sure if you've started the draft language for the limited access but here is what kathryn put for PCR, which we can do something similar for this:

"Note:
This feature is in limited access and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change."

alicia-l2

final changes LGTM, thank you!

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 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 force-pushed the jl/doc-11599 branch 3 times, most recently from f737eba to 38bd1c0 Compare August 5, 2025 19:42

alicia-l2 reviewed Aug 6, 2025

View reviewed changes

src/current/releases/cloud.md Outdated Show resolved Hide resolved

Add documentation for new backup and restore cloud API endpoints

810e574

jhlodin added 7 commits August 11, 2025 17:39

Add cross-cluster restore operation examples

2bc11c7

Add missing view backups snippet

ac82b7a

Slight rewording

9664c47

Corrections

9c82b16

Address eng and PM comments

0b0a320

Adjust restore_opt to be advanced only

d1a7f1b

Remove outdated cluster wipe warning

7f7ea4b

jhlodin force-pushed the jl/doc-11599 branch from 38bd1c0 to 7f7ea4b Compare August 11, 2025 21:40

Add limited preview notes

e001657

jhlodin force-pushed the jl/doc-11599 branch from 157b677 to e001657 Compare August 11, 2025 21:49

alicia-l2 approved these changes Aug 11, 2025

View reviewed changes

jhlodin merged commit 39e2eb5 into main Aug 12, 2025
5 checks passed

jhlodin deleted the jl/doc-11599 branch August 12, 2025 15:08

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

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

Uh oh!

Conversation

jhlodin commented Jul 28, 2025 • edited 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!

Uh oh!

jhlodin commented Jul 28, 2025 •

edited

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