Merge pull request #50 from ClickHouse/BYOB

Add Bring your own Buckets for Backup page

Author: Blargian

docs/en/cloud/manage/bring-your-own-bucket.md

@@ -0,0 +1,152 @@
+---
+sidebar_label: Bring your own Bucket
+slug: /en/cloud/manage/bring-your-own-bucket
+title: Bring your own Bucket for Backups
+---
+
+import EnterprisePlanFeatureBadge from '@theme/badges/EnterprisePlanFeatureBadge'
+
+<EnterprisePlanFeatureBadge/>
+
+ClickHouse Cloud supports taking backups to your own cloud service provider (CSP) account (AWS S3, Google Cloud Storage, or Azure Blob Storage).
+For details of how ClickHouse Cloud backups work, including “full” vs. “incremental” backups, see the [backups](./backups.md) docs.
+
+Here we show examples of how to take full and incremental backups to AWS, GCP, Azure object storage as well as how to restore from the backups.
+
+:::note
+Users should be aware that any usage where backups are being exported to a different region in the same cloud provider, or to another cloud provider (in the same or different region) will incur [data transfer](./network-data-transfer.mdx) charges.
+:::
+
+## Requirements
+
+You will need the following details to export/restore backups to your own CSP storage bucket.
+
+### AWS
+
+1. AWS S3 endpoint, in the format:
+
+    ```text
+    s3://<bucket_name>.s3.amazonaws.com/<directory>
+    ```
+
+    For example: 
+    ```text
+    s3://testchbackups.s3.amazonaws.com/backups/`
+   ```
+    Where:
+   - `testchbackups` is the name of the S3 bucket to export backups to.
+   - `backups` is an optional subdirectory.
+
+
+2. AWS access key and secret.
+
+### Azure
+
+1. Azure storage connection string.
+2. Azure container name in the storage account.
+3. Azure Blob within the container.
+
+### Google Cloud Storage (GCS)
+
+1. GCS endpoint, in the format:
+
+    ```text
+    https://storage.googleapis.com/<bucket_name>/
+    ```
+2. Access HMAC key and HMAC secret.
+
+# Backup / Restore
+
+## Backup / Restore to AWS S3 Bucket
+
+### Take a DB Backup
+
+**Full Backup**
+
+```sql
+BACKUP DATABASE test_backups TO 
+S3('https://testchbackups.s3.amazonaws.com/backups/<uuid>', '<key id>', '<key secret>')
+```
+
+Where `uuid` is a unique identifier, used to differentiate a set of backups.
+
+:::note
+You will need to use a different UUID for each new backup in this subdirectory, otherwise you will get a `BACKUP_ALREADY_EXISTS` error.
+For example, if you are taking daily backups, you will need to use a new UUID each day.  
+:::
+
+**Incremental Backup**
+
+```sql
+BACKUP DATABASE test_backups 
+TO S3('https://testchbackups.s3.amazonaws.com/backups/<uuid>', '<key id>', '<key secret>') 
+SETTINGS base_backup = S3('https://testchbackups.s3.amazonaws.com/backups/<base-backup-uuid>', '<key id>', '<key secret>')
+```
+
+### Restore from a backup
+
+```sql
+RESTORE DATABASE test_backups 
+AS test_backups_restored 
+FROM S3('https://testchbackups.s3.amazonaws.com/backups/<uuid>', '<key id>', '<key secret>')
+```
+
+See: [Configuring BACKUP/RESTORE to use an S3 Endpoint](/docs/en/operations/backup#configuring-backuprestore-to-use-an-s3-endpoint) for more details.
+
+## Backup / Restore to Azure Blob Storage
+
+### Take a DB Backup
+
+**Full Backup**
+
+```sql
+BACKUP DATABASE test_backups TO AzureBlobStorage('<AzureBlobStorage endpoint connection string>', '<container>', '<blob>/<uuid>');
+```
+
+Where `uuid` is a unique identifier, used to differentiate a set of backups.
+
+**Incremental Backup**
+
+```sql
+BACKUP DATABASE test_backups 
+TO AzureBlobStorage('<AzureBlobStorage endpoint connection string>', '<container>', '<blob>/<uuid>/my_incremental') 
+SETTINGS base_backup = AzureBlobStorage('<AzureBlobStorage endpoint connection string>', '<container>', '<blob>/<uuid>')
+```
+
+### Restore from a backup
+
+```sql
+RESTORE DATABASE test_backups 
+AS test_backups_restored_azure 
+FROM AzureBlobStorage('<AzureBlobStorage endpoint connection string>', '<container>', '<blob>/<uuid>')
+```
+
+See: [Configuring BACKUP/RESTORE to use an S3 Endpoint](/docs/en/operations/backup#configuring-backuprestore-to-use-an-azureblobstorage-endpoint) for more details.
+
+## Backup / Restore to Azure Blob Storage
+
+### Take a DB Backup
+
+**Full Backup**
+
+```sql
+BACKUP DATABASE test_backups 
+TO S3('https://storage.googleapis.com/<bucket>/<uuid>', <hmac-key>', <hmac-secret>)
+```
+Where `uuid` is a unique identifier, used to differentiate a set of backups.
+
+**Incremental Backup**
+
+```sql
+BACKUP DATABASE test_backups 
+TO S3('https://storage.googleapis.com/test_gcs_backups/<uuid>/my_incremental', 'key', 'secret')
+SETTINGS base_backup = S3('https://storage.googleapis.com/test_gcs_backups/<uuid>', 'key', 'secret')
+```
+
+### Restore from a backup
+
+```sql
+RESTORE DATABASE test_backups 
+AS test_backups_restored_gcs 
+FROM S3('https://storage.googleapis.com/test_gcs_backups/<uuid>', 'key', 'secret')
+```

sidebars.js

@@ -212,6 +212,7 @@ const sidebars = {
         "en/cloud/manage/cloud-tiers",
         "en/cloud/manage/integrations",
         "en/cloud/manage/backups",
+        "en/cloud/manage/bring-your-own-bucket",
         {
           type: "category",
           label: "Monitoring",