Skip to content

Add callouts for S3-compatible storage support policy #20503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 10, 2025
Merged

Add callouts for S3-compatible storage support policy #20503

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
075e8d4
Add callouts for S3-compatible storage support policy
jhlodin Oct 6, 2025
fe1475c
Alicia and Michael comments
jhlodin Oct 7, 2025
0b78dfd
Strengthen support statement
jhlodin Oct 9, 2025
cb3a675
Merge branch 'main' into jl/doc-14822
jhlodin Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions src/current/_includes/common/s3-support-notice.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{% if page.path contains "cockroachcloud" %}
{{ site.data.alerts.callout_danger }}
Cockroach Labs does not officially support S3-compatible storage solutions other than AWS S3, Google Cloud Storage (GCS), and Azure Blob Storage. Some common compatibility issues may be fixed by adding the `AWS_SKIP_CHECKSUM` option to the S3 URLs.

The [Cockroach Labs Support team]({% link {{ site.current_cloud_version }}/support-resources.md %}) is available to offer assistance where possible. If you encounter issues when using unsupported S3-compatible storage, drivers, or frameworks, contact the maintainer directly.
{{ site.data.alerts.end }}
{% else %}
{{ site.data.alerts.callout_danger }}
Cockroach Labs does not officially support S3-compatible storage solutions other than AWS S3, Google Cloud Storage (GCS), and Azure Blob Storage.{% if page.version.version !="v24.1" %} Some common compatibility issues may be fixed by adding the `AWS_SKIP_CHECKSUM` option to the S3 URLs.{% endif %}.
Copy link
Contributor

@rimadeodhar rimadeodhar Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This language looks good! Thanks for the update.
Nit: remove the double period at the end of this sentence (after the option to S3 URLs bit).



The [Cockroach Labs Support team]({% link {{page.version.version}}/support-resources.md %}) is available to offer assistance where possible. If you encounter issues when using unsupported S3-compatible storage, drivers, or frameworks, contact the maintainer.
Copy link

@msbutler msbutler Oct 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this language is a lot better. could you provide a preview web page so i can understand how this renders? There are several repeat lines in this page, but maybe it renders nicely.

Copy link
Contributor Author

@jhlodin jhlodin Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure thing, here's how it renders - https://deploy-preview-20503--cockroachdb-docs.netlify.app/docs/stable/backup-and-restore-overview#backup-storage

The repeat lines are because I'm using some in-page logic to slightly adjust the text based on which page it's on. For the v24.1 version of the page, exclude the line about AWS_SKIP_CHECKSUM. For the pages in the Cloud docs, the link to the support page needs to be modified in order to resolve. Etc.

Copy link
Contributor Author

@jhlodin jhlodin Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For ease of review on docs PRs, about ~10 minutes after a commit to a docs PR is pushed, there should be a comment automatically posted by Netlify that (if successful) includes a link to a render preview of the PR. Just FYI for future reference.

{{ site.data.alerts.end }}
{% endif %}
2 changes: 2 additions & 0 deletions src/current/cockroachcloud/backup-and-restore-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,8 @@ We recommend taking backups to [cloud storage]({% link {{site.current_cloud_vers
- [Example file URLs]({% link {{site.current_cloud_version}}/use-cloud-storage.md %}#example-file-urls) to form the URL that you pass to `BACKUP` and `RESTORE` statements.
- [Authentication]({% link {{site.current_cloud_version}}/cloud-storage-authentication.md %}) to set up authentication to a cloud storage bucket and include those credentials in the URL.

{% include common/s3-support-notice.md %}

For detail on additional cloud storage features CockroachDB supports:

- Prevent backups from being overwritten or deleted with [immutable storage buckets]({% link {{site.current_cloud_version}}/use-cloud-storage.md %}#immutable-storage).
Expand Down
15 changes: 11 additions & 4 deletions src/current/v24.1/backup-and-restore-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,15 @@ docs_area: manage

CockroachDB is built to be [fault-tolerant with automatic recovery]({% link {{ page.version.version }}/demo-fault-tolerance-and-recovery.md %}), but sometimes disasters happen. Backup and restore is an important part of a robust disaster recovery plan. CockroachDB {{ site.data.products.core }} clusters provide a range of [backup and restore features](#backup-and-restore-support).

- [Backup and restore product support](#backup-and-restore-support)
- [Schedules](#scheduled-backups) for periodic backups
- [SQL statements](#backup-and-restore-sql-statements) for working with backups and restores
- [Storage](#backup-storage) for backups
- [Backup and restore support](#backup-and-restore-support)
- [Additional backup and restore features](#additional-backup-and-restore-features)
- [Scheduled backups](#scheduled-backups)
- [Backup jobs with locality requirements](#backup-jobs-with-locality-requirements)
- [Backup and restore SQL statements](#backup-and-restore-sql-statements)
- [Backup storage](#backup-storage)
- [Backup and restore observability](#backup-and-restore-observability)
- [Video demo](#video-demo)
- [See also](#see-also)

You can create full or incremental backups of a [cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster), [database]({% link {{ page.version.version }}/backup.md %}#back-up-a-database), or [table]({% link {{ page.version.version }}/backup.md %}#back-up-a-table-or-view). Taking regular backups of your data is an operational best practice.

Expand Down Expand Up @@ -130,6 +135,8 @@ We recommend taking backups to [cloud storage]({% link {{ page.version.version }
- [Example file URLs]({% link {{ page.version.version }}/use-cloud-storage.md %}#example-file-urls) to form the URL that you pass to `BACKUP` and `RESTORE` statements.
- [Authentication]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) to set up authentication to a cloud storage bucket and include those credentials in the URL.

{% include common/s3-support-notice.md %}

For detail on additional cloud storage features CockroachDB supports:

- Prevent backups from being overwritten or deleted with [immutable storage buckets]({% link {{ page.version.version }}/use-cloud-storage.md %}#immutable-storage).
Expand Down
6 changes: 5 additions & 1 deletion src/current/v24.1/backup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,13 @@ To view the contents of an backup created with the `BACKUP` statement, use [`SHO

### Storage considerations

- Cockroach Labs tests functionality with AWS S3, Google Cloud Storage (GCS), and Azure Blob Storage. Other S3-compatible storage solutions are untested.
- [HTTP storage]({% link {{ page.version.version }}/use-a-local-file-server.md %}) is not supported for `BACKUP` and `RESTORE`.
- Modifying backup files in the storage location could invalidate a backup, and therefore, prevent a restore. In v22.1 and later, **we recommend enabling [object locking]({% link {{ page.version.version }}/use-cloud-storage.md %}#immutable-storage) in your cloud storage bucket.**
- While Cockroach Labs actively tests Amazon S3, Google Cloud Storage, and Azure Storage, we **do not** test [S3-compatible services]({% link {{ page.version.version }}/use-cloud-storage.md %}) (e.g., [MinIO](https://min.io/), [Red Hat Ceph](https://docs.ceph.com/en/pacific/radosgw/s3/)).

{{site.data.alerts.callout_danger}}
Cockroach Labs does not officially support untested storage systems. If you encounter issues when using unsupported S3-compatible storage, drivers, or frameworks, contact the maintainer.
{{site.data.alerts.end}}

## Required privileges

Expand Down
15 changes: 11 additions & 4 deletions src/current/v24.3/backup-and-restore-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,15 @@ docs_area: manage

CockroachDB is built to be [fault-tolerant with automatic recovery]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), but sometimes disasters happen. Backup and restore is an important part of a robust disaster recovery plan. CockroachDB {{ site.data.products.core }} clusters provide a range of [backup and restore features](#backup-and-restore-support).

- [Backup and restore product support](#backup-and-restore-support)
- [Schedules](#scheduled-backups) for periodic backups
- [SQL statements](#backup-and-restore-sql-statements) for working with backups and restores
- [Storage](#backup-storage) for backups
- [Backup and restore support](#backup-and-restore-support)
- [Additional backup and restore features](#additional-backup-and-restore-features)
- [Scheduled backups](#scheduled-backups)
- [Backup jobs with locality requirements](#backup-jobs-with-locality-requirements)
- [Backup and restore SQL statements](#backup-and-restore-sql-statements)
- [Backup storage](#backup-storage)
- [Backup and restore observability](#backup-and-restore-observability)
- [Video demo](#video-demo)
- [See also](#see-also)

You can create full or incremental backups of a [cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster), [database]({% link {{ page.version.version }}/backup.md %}#back-up-a-database), or [table]({% link {{ page.version.version }}/backup.md %}#back-up-a-table-or-view). Taking regular backups of your data is an operational best practice.

Expand Down Expand Up @@ -130,6 +135,8 @@ We recommend taking backups to [cloud storage]({% link {{ page.version.version }
- [Example file URLs]({% link {{ page.version.version }}/use-cloud-storage.md %}#example-file-urls) to form the URL that you pass to `BACKUP` and `RESTORE` statements.
- [Authentication]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) to set up authentication to a cloud storage bucket and include those credentials in the URL.

{% include common/s3-support-notice.md %}

For detail on additional cloud storage features CockroachDB supports:

- Prevent backups from being overwritten or deleted with [immutable storage buckets]({% link {{ page.version.version }}/use-cloud-storage.md %}#immutable-storage).
Expand Down
6 changes: 5 additions & 1 deletion src/current/v24.3/backup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,13 @@ To view the contents of an backup created with the `BACKUP` statement, use [`SHO

### Storage considerations

- Cockroach Labs tests functionality with AWS S3, Google Cloud Storage (GCS), and Azure Blob Storage. Other S3-compatible storage solutions are untested, but common compatibility issues in v24.3 and later may be fixed by adding the `AWS_SKIP_CHECKSUM` option to the S3 URLs.
- [HTTP storage]({% link {{ page.version.version }}/use-a-local-file-server.md %}) is not supported for `BACKUP` and `RESTORE`.
- Modifying backup files in the storage location could invalidate a backup, and therefore, prevent a restore. In v22.1 and later, **we recommend enabling [object locking]({% link {{ page.version.version }}/use-cloud-storage.md %}#immutable-storage) in your cloud storage bucket.**
- While Cockroach Labs actively tests Amazon S3, Google Cloud Storage, and Azure Storage, we **do not** test [S3-compatible services]({% link {{ page.version.version }}/use-cloud-storage.md %}) (e.g., [MinIO](https://min.io/), [Red Hat Ceph](https://docs.ceph.com/en/pacific/radosgw/s3/)).

{{site.data.alerts.callout_danger}}
Cockroach Labs does not officially support untested storage systems. If you encounter issues when using unsupported S3-compatible storage, drivers, or frameworks, contact the maintainer.
{{site.data.alerts.end}}

## Required privileges

Expand Down
15 changes: 11 additions & 4 deletions src/current/v25.2/backup-and-restore-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,15 @@ docs_area: manage

CockroachDB is built to be [fault-tolerant with automatic recovery]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), but sometimes disasters happen. Backup and restore is an important part of a robust disaster recovery plan. CockroachDB {{ site.data.products.core }} clusters provide a range of [backup and restore features](#backup-and-restore-support).

- [Backup and restore product support](#backup-and-restore-support)
- [Schedules](#scheduled-backups) for periodic backups
- [SQL statements](#backup-and-restore-sql-statements) for working with backups and restores
- [Storage](#backup-storage) for backups
- [Backup and restore support](#backup-and-restore-support)
- [Additional backup and restore features](#additional-backup-and-restore-features)
- [Scheduled backups](#scheduled-backups)
- [Backup jobs with locality requirements](#backup-jobs-with-locality-requirements)
- [Backup and restore SQL statements](#backup-and-restore-sql-statements)
- [Backup storage](#backup-storage)
- [Backup and restore observability](#backup-and-restore-observability)
- [Video demo](#video-demo)
- [See also](#see-also)

You can create full or incremental backups of a [cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster), [database]({% link {{ page.version.version }}/backup.md %}#back-up-a-database), or [table]({% link {{ page.version.version }}/backup.md %}#back-up-a-table-or-view). Taking regular backups of your data is an operational best practice.

Expand Down Expand Up @@ -130,6 +135,8 @@ We recommend taking backups to [cloud storage]({% link {{ page.version.version }
- [Example file URLs]({% link {{ page.version.version }}/use-cloud-storage.md %}#example-file-urls) to form the URL that you pass to `BACKUP` and `RESTORE` statements.
- [Authentication]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) to set up authentication to a cloud storage bucket and include those credentials in the URL.

{% include common/s3-support-notice.md %}

For detail on additional cloud storage features CockroachDB supports:

- Prevent backups from being overwritten or deleted with [immutable storage buckets]({% link {{ page.version.version }}/use-cloud-storage.md %}#immutable-storage).
Expand Down
5 changes: 4 additions & 1 deletion src/current/v25.2/backup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,13 @@ To view the contents of an backup created with the `BACKUP` statement, use [`SHO

### Storage considerations

- Cockroach Labs tests functionality with AWS S3, Google Cloud Storage (GCS), and Azure Blob Storage. Other S3-compatible storage solutions are untested, but common compatibility issues in v24.3 and later may be fixed by adding the `AWS_SKIP_CHECKSUM` option to the S3 URLs.
- [HTTP storage]({% link {{ page.version.version }}/use-a-local-file-server.md %}) is not supported for `BACKUP` and `RESTORE`.
- Modifying backup files in the storage location could invalidate a backup, and therefore, prevent a restore. In v22.1 and later, **we recommend enabling [object locking]({% link {{ page.version.version }}/use-cloud-storage.md %}#immutable-storage) in your cloud storage bucket.**
- While Cockroach Labs actively tests Amazon S3, Google Cloud Storage, and Azure Storage, we **do not** test [S3-compatible services]({% link {{ page.version.version }}/use-cloud-storage.md %}) (e.g., [MinIO](https://min.io/), [Red Hat Ceph](https://docs.ceph.com/en/pacific/radosgw/s3/)).

{{site.data.alerts.callout_danger}}
Cockroach Labs does not officially support untested storage systems. If you encounter issues when using unsupported S3-compatible storage, drivers, or frameworks, contact the maintainer.
{{site.data.alerts.end}}
{{site.data.alerts.callout_success}}
{% include {{ page.version.version }}/backups/external-storage-check-tip.md %}
{{site.data.alerts.end}}
Expand Down
15 changes: 11 additions & 4 deletions src/current/v25.3/backup-and-restore-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,15 @@ docs_area: manage

CockroachDB is built to be [fault-tolerant with automatic recovery]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), but sometimes disasters happen. Backup and restore is an important part of a robust disaster recovery plan. CockroachDB {{ site.data.products.core }} clusters provide a range of [backup and restore features](#backup-and-restore-support).

- [Backup and restore product support](#backup-and-restore-support)
- [Schedules](#scheduled-backups) for periodic backups
- [SQL statements](#backup-and-restore-sql-statements) for working with backups and restores
- [Storage](#backup-storage) for backups
- [Backup and restore support](#backup-and-restore-support)
- [Additional backup and restore features](#additional-backup-and-restore-features)
- [Scheduled backups](#scheduled-backups)
- [Backup jobs with locality requirements](#backup-jobs-with-locality-requirements)
- [Backup and restore SQL statements](#backup-and-restore-sql-statements)
- [Backup storage](#backup-storage)
- [Backup and restore observability](#backup-and-restore-observability)
- [Video demo](#video-demo)
- [See also](#see-also)

You can create full or incremental backups of a [cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster), [database]({% link {{ page.version.version }}/backup.md %}#back-up-a-database), or [table]({% link {{ page.version.version }}/backup.md %}#back-up-a-table-or-view). Taking regular backups of your data is an operational best practice.

Expand Down Expand Up @@ -130,6 +135,8 @@ We recommend taking backups to [cloud storage]({% link {{ page.version.version }
- [Example file URLs]({% link {{ page.version.version }}/use-cloud-storage.md %}#example-file-urls) to form the URL that you pass to `BACKUP` and `RESTORE` statements.
- [Authentication]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) to set up authentication to a cloud storage bucket and include those credentials in the URL.

{% include common/s3-support-notice.md %}

For detail on additional cloud storage features CockroachDB supports:

- Prevent backups from being overwritten or deleted with [immutable storage buckets]({% link {{ page.version.version }}/use-cloud-storage.md %}#immutable-storage).
Expand Down
5 changes: 4 additions & 1 deletion src/current/v25.3/backup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,13 @@ To view the contents of an backup created with the `BACKUP` statement, use [`SHO

### Storage considerations

- Cockroach Labs tests functionality with AWS S3, Google Cloud Storage (GCS), and Azure Blob Storage. Other S3-compatible storage solutions are untested, but common compatibility issues in v24.3 and later may be fixed by adding the `AWS_SKIP_CHECKSUM` option to the S3 URLs.
- [HTTP storage]({% link {{ page.version.version }}/use-a-local-file-server.md %}) is not supported for `BACKUP` and `RESTORE`.
- Modifying backup files in the storage location could invalidate a backup, and therefore, prevent a restore. In v22.1 and later, **we recommend enabling [object locking]({% link {{ page.version.version }}/use-cloud-storage.md %}#immutable-storage) in your cloud storage bucket.**
- While Cockroach Labs actively tests Amazon S3, Google Cloud Storage, and Azure Storage, we **do not** test [S3-compatible services]({% link {{ page.version.version }}/use-cloud-storage.md %}) (e.g., [MinIO](https://min.io/), [Red Hat Ceph](https://docs.ceph.com/en/pacific/radosgw/s3/)).

{{site.data.alerts.callout_danger}}
Cockroach Labs does not officially support untested storage systems. If you encounter issues when using unsupported S3-compatible storage, drivers, or frameworks, contact the maintainer.
{{site.data.alerts.end}}
{{site.data.alerts.callout_success}}
{% include {{ page.version.version }}/backups/external-storage-check-tip.md %}
{{site.data.alerts.end}}
Expand Down
15 changes: 11 additions & 4 deletions src/current/v25.4/backup-and-restore-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,15 @@ docs_area: manage

CockroachDB is built to be [fault-tolerant with automatic recovery]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), but sometimes disasters happen. Backup and restore is an important part of a robust disaster recovery plan. CockroachDB {{ site.data.products.core }} clusters provide a range of [backup and restore features](#backup-and-restore-support).

- [Backup and restore product support](#backup-and-restore-support)
- [Schedules](#scheduled-backups) for periodic backups
- [SQL statements](#backup-and-restore-sql-statements) for working with backups and restores
- [Storage](#backup-storage) for backups
- [Backup and restore support](#backup-and-restore-support)
- [Additional backup and restore features](#additional-backup-and-restore-features)
- [Scheduled backups](#scheduled-backups)
- [Backup jobs with locality requirements](#backup-jobs-with-locality-requirements)
- [Backup and restore SQL statements](#backup-and-restore-sql-statements)
- [Backup storage](#backup-storage)
- [Backup and restore observability](#backup-and-restore-observability)
- [Video demo](#video-demo)
- [See also](#see-also)

You can create full or incremental backups of a [cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster), [database]({% link {{ page.version.version }}/backup.md %}#back-up-a-database), or [table]({% link {{ page.version.version }}/backup.md %}#back-up-a-table-or-view). Taking regular backups of your data is an operational best practice.

Expand Down Expand Up @@ -130,6 +135,8 @@ We recommend taking backups to [cloud storage]({% link {{ page.version.version }
- [Example file URLs]({% link {{ page.version.version }}/use-cloud-storage.md %}#example-file-urls) to form the URL that you pass to `BACKUP` and `RESTORE` statements.
- [Authentication]({% link {{ page.version.version }}/cloud-storage-authentication.md %}) to set up authentication to a cloud storage bucket and include those credentials in the URL.

{% include common/s3-support-notice.md %}

For detail on additional cloud storage features CockroachDB supports:

- Prevent backups from being overwritten or deleted with [immutable storage buckets]({% link {{ page.version.version }}/use-cloud-storage.md %}#immutable-storage).
Expand Down
Loading
Loading