From 6704d3fba22014498c1b8441ba3fd1dba75cd312 Mon Sep 17 00:00:00 2001 From: michael Date: Fri, 4 Sep 2026 11:09:20 +0200 Subject: [PATCH] docs: refresh backup/restore section against R26.3, add control-plane backup for plain Linux MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Validated every command and CRD field against sbcli R26.3 and the operator main branch. Changes: Non-Kubernetes (docs/non-kubernetes/operations/data-protection): - backup-recovery.md: add the missing 'Configuring the Backup Target' section (cluster create/add --use-backup JSON schema); fix 'backup restore' (no --cluster-id anymore, cluster derives from the pool; default target node is automatic placement, not the node that took the backup); document restore preconditions (complete chain, matching active S3 source), encryption/KMS and allowed-hosts preservation, and merge-based retention; replace the embedded Kubernetes CRD half (stale simplybk/ annotation) with a pointer to the Kubernetes page. - control-plane-backup.md (NEW): sbctl db-backup config/create/list/ status/restore for Docker deployments — defaults (3h, /etc/foundationdb/backup), S3 destination, automatic scheduling, and the clear-before-restore danger note. - index.md: list the new page. Kubernetes (docs/kubernetes/operations/data-protection): - backup-recovery.md: document the BackupImport CRD (cross-cluster restore without a backup-source switch — the operator resolves the source cluster's credentials); add StorageBackup.spec.snapshotName and the fsType capture/preservation behaviour; fix BackupRestore.targetNode default; StorageCluster backup spec field table incl. secondaryTarget; align retention wording with the merge semantics; cross-link the CLI and FoundationDB pages. Quality gates: no errors in the touched files (remaining syntax-gate errors are pre-existing links to build-generated reference/cli pages). Co-Authored-By: Claude Fable 5 --- .../data-protection/backup-recovery.md | 110 ++++-- .../data-protection/backup-recovery.md | 345 +++++------------- .../data-protection/control-plane-backup.md | 85 +++++ .../operations/data-protection/index.md | 12 +- 4 files changed, 267 insertions(+), 285 deletions(-) create mode 100644 docs/non-kubernetes/operations/data-protection/control-plane-backup.md diff --git a/docs/kubernetes/operations/data-protection/backup-recovery.md b/docs/kubernetes/operations/data-protection/backup-recovery.md index f3c8d32d..80d50a96 100644 --- a/docs/kubernetes/operations/data-protection/backup-recovery.md +++ b/docs/kubernetes/operations/data-protection/backup-recovery.md @@ -4,11 +4,11 @@ description: "Snapshot-based backup and recovery to Amazon S3 or S3-compatible o weight: 10510 --- -Simplyblock provides snapshot-based backup and recovery to Amazon S3 or S3-compatible object storage. Backups can be -managed via the CLI or through Kubernetes CRDs. - -In Kubernetes environments, backups can be managed declaratively using Custom Resource Definitions (CRDs). This -is especially useful for automated backup workflows integrated with Kubernetes-native tooling. +Simplyblock provides snapshot-based backup and recovery to Amazon S3 or S3-compatible object storage. In +Kubernetes environments, backups are managed declaratively using Custom Resource Definitions (CRDs). This is +especially useful for automated backup workflows integrated with Kubernetes-native tooling. The same engine can +also be driven through the CLI, see +[Backup and Recovery on plain Linux](../../../non-kubernetes/operations/data-protection/backup-recovery.md). ### Prerequisites @@ -63,6 +63,14 @@ spec: withCompression: false ``` +| Field | Default | Description | +|-----------------------------|---------|----------------------------------------------------------------------------------| +| `credentialsSecretRef.name` | — | Secret with `access_key_id` and `secret_access_key`. **Required**. | +| `localEndpoint` | AWS S3 | Endpoint URL for S3-compatible storage (e.g., MinIO). Leave unset for Amazon S3. | +| `snapshotBackups` | `true` | Allow snapshots to be used as backup sources. | +| `withCompression` | `false` | Compress backup data before upload. | +| `secondaryTarget` | `0` | Secondary backup target selector (advanced). | + See the [Operator Reference](../../../reference/operator/reference.md#storagecluster) for all available `backup` spec fields. ### StorageBackup CRD @@ -99,10 +107,14 @@ my-pvc-backup Done my-pvc 7fab02f8-03f6-4e76-a9ac-78b63b1ce8ef backup-m #### Spec Fields -| Field | Type | Description | -|---------------|--------|--------------------------------------------------| -| `clusterName` | string | Name of the target StorageCluster. **Required**. | -| `pvcRef.name` | string | Name of the PVC to back up. **Required**. | +| Field | Type | Description | +|----------------|--------|------------------------------------------------------------------| +| `clusterName` | string | Name of the target StorageCluster. **Required**. | +| `pvcRef.name` | string | Name of the PVC to back up. **Required**. | +| `snapshotName` | string | Overrides the name of the internally created snapshot. Optional. | + +The backup also records the source volume's filesystem type in its status (`fsType`), so a later restore mounts +the restored volume with the same filesystem regardless of the target StorageClass defaults. #### Status Fields @@ -153,18 +165,19 @@ my-restore Done my-pvc-backup restored-pvc 79s ``` The phase transitions from `InProgress` → `PVCBinding` → `Done`. Once `Done`, the new PVC is ready to attach -to a pod. +to a pod. The restored PersistentVolume is created with the filesystem type recorded in the source backup, and an +encrypted source volume is restored encrypted. #### Spec Fields -| Field | Type | Description | -|-----------------------------|--------|---------------------------------------------------------------------------------| -| `clusterName` | string | Name of the target StorageCluster. **Required**. | -| `backupRef.name` | string | Name of the `StorageBackup` to restore from. **Required**. | -| `targetPool` | string | Pool to restore into. Defaults to the source backup PVC's pool. | -| `targetNode` | string | Storage node to restore to. Defaults to the node that held the original backup. | -| `pvcTemplate.metadata.name` | string | Name of the new PVC to create. **Required**. | -| `pvcTemplate.spec` | object | PVC spec (accessModes, resources, etc.). | +| Field | Type | Description | +|-----------------------------|--------|-----------------------------------------------------------------------------| +| `clusterName` | string | Name of the target StorageCluster. **Required**. | +| `backupRef.name` | string | Name of the `StorageBackup` to restore from. **Required**. | +| `targetPool` | string | Pool to restore into. Defaults to the source backup PVC's pool. | +| `targetNode` | string | Storage node to restore to. Defaults to automatic placement in the cluster. | +| `pvcTemplate.metadata.name` | string | Name of the new PVC to create. **Required**. | +| `pvcTemplate.spec` | object | PVC spec (accessModes, resources, etc.). | !!! warning A backup can only be restored to the same namespace as the `BackupRestore` object. @@ -194,12 +207,16 @@ EOF | Field | Type | Description | |---------------|--------|-------------------------------------------------------------------| | `clusterName` | string | Name of the target StorageCluster. **Required**. | -| `maxVersions` | int | Maximum number of backup versions to retain. | -| `maxAge` | string | Maximum backup age before cleanup (e.g., `7d`, `12h`). | +| `maxVersions` | int | Maximum number of completed backup versions to retain. | +| `maxAge` | string | Maximum backup age (e.g., `7d`, `12h`, `30m`). | | `schedule` | string | Tiered backup schedule as space-separated `interval,count` pairs. | -The schedule format is a space-separated list of `interval,count` pairs. For example, `15m,4 60m,11 24h,7` means: -take a backup every 15 minutes (keep the 4 most recent), every 60 minutes (keep 11), and every 24 hours (keep 7). +The schedule format is a space-separated list of `interval,count` pairs with strictly increasing intervals. For +example, `15m,4 60m,11 24h,7` means: take a backup every 15 minutes (keep the 4 most recent), every 60 minutes +(keep 11), and every 24 hours (keep 7). + +Retention does not delete data: when `maxVersions` or `maxAge` is exceeded, the oldest backup is merged into the +next one, so the number of restore points shrinks while the backup chain stays complete. #### Attaching a Policy to a PVC @@ -228,3 +245,52 @@ To detach a policy from a PVC (existing backups are not deleted): ```bash title="Detach a backup policy" kubectl annotate pvc my-pvc -n simplyblock simplyblock.io/backup-policy- ``` + +### BackupImport CRD (Cross-Cluster Restore) + +A `BackupImport` makes a backup taken on one simplyblock cluster restorable on another. Both clusters must be +represented as `StorageCluster` resources managed by the same operator, and the target cluster's storage nodes +must be able to reach the source cluster's S3 bucket. + +Find the backup to import on the source cluster (`BACKUPID` column of `kubectl get storagebackup`), then create +the import against the target cluster: + +```yaml title="Import a backup from another cluster" +kubectl apply -f - <<'MANIFEST' +apiVersion: storage.simplyblock.io/v1alpha1 +kind: BackupImport +metadata: + name: my-import + namespace: simplyblock +spec: + sourceClusterName: cluster-a + sourceBackupID: 7fab02f8-03f6-4e76-a9ac-78b63b1ce8ef + targetClusterName: cluster-b +MANIFEST +``` + +The phase transitions from `Pending` → `Exporting` → `Importing` → `Done`. On completion, the controller has +imported the backup metadata into the target cluster and created a `StorageBackup` resource marked as imported; +its name is published in `status.storageBackupRef`. + +```bash title="Check the import" +kubectl -n simplyblock get backupimport my-import -o jsonpath='{.status.storageBackupRef}' +``` + +Reference that `StorageBackup` in a regular [`BackupRestore`](#backuprestore-crd) to restore it. The restore +controller detects the foreign source and reads from the source cluster's bucket using the source +`StorageCluster`'s own backup credentials — unlike the CLI flow, no cluster-wide backup-source switch is needed, +and local backups continue uninterrupted. + +#### Spec Fields + +| Field | Type | Description | +|---------------------|--------|------------------------------------------------------------------------| +| `sourceClusterName` | string | StorageCluster name of the cluster that owns the backup. **Required**. | +| `sourceBackupID` | string | Backup UUID on the source cluster. **Required**. | +| `targetClusterName` | string | StorageCluster name of the cluster to import into. **Required**. | + +## Control-Plane Backups + +The CRDs on this page protect volume data. The control-plane database itself is backed up separately, see +[FoundationDB Backup and Restore](foundationdb-backup.md). diff --git a/docs/non-kubernetes/operations/data-protection/backup-recovery.md b/docs/non-kubernetes/operations/data-protection/backup-recovery.md index 3a08ff5d..5324fed1 100644 --- a/docs/non-kubernetes/operations/data-protection/backup-recovery.md +++ b/docs/non-kubernetes/operations/data-protection/backup-recovery.md @@ -4,17 +4,50 @@ description: "Snapshot-based backup and recovery to Amazon S3 or S3-compatible o weight: 10510 --- -Simplyblock provides snapshot-based backup and recovery to Amazon S3 or S3-compatible object storage. Backups can be -managed via the CLI or through Kubernetes CRDs. +Simplyblock provides snapshot-based backup and recovery to Amazon S3 or S3-compatible object storage. A backup is +an incremental copy of a volume snapshot; restoring reconstructs the data from the backup chain into a new volume. -For Kubernetes deployment and configuration details, see -[Kubernetes Helm Chart Parameters](../../../reference/kubernetes/index.md). +On plain Linux, backups are managed through the CLI. In Kubernetes environments, the same engine is driven +declaratively through CRDs, see +[Backup and Recovery on Kubernetes](../../../kubernetes/operations/data-protection/backup-recovery.md). -## CLI Operations +## Configuring the Backup Target -### Creating a Backup +The S3 target is configured at cluster creation time by passing a JSON configuration file: -Backups are created from existing volume snapshots. First, create a snapshot of the volume, then back it up: +```bash title="Enable backups at cluster creation" +{{ cliname }} cluster create ... --use-backup backup-config.json +``` + +The same parameter is available on `cluster add`. The configuration file has the following format: + +```json title="backup-config.json" +{ + "access_key_id": "", + "secret_access_key": "", + "local_endpoint": "http://minio.internal:9000", + "bucket_name": "my-backup-bucket", + "with_compression": false, + "snapshot_backups": true +} +``` + +| Key | Default | Description | +|---------------------|-----------------------------------|----------------------------------------------------------------------------------| +| `access_key_id` | — | S3 access key. **Required**. | +| `secret_access_key` | — | S3 secret key. **Required**. | +| `local_endpoint` | AWS S3 | Endpoint URL for S3-compatible storage (e.g., MinIO). Leave unset for Amazon S3. | +| `bucket_name` | `simplyblock-backup-` | Bucket for backup data. Created automatically if it does not exist. | +| `with_compression` | `false` | Compress backup data before upload. | +| `snapshot_backups` | `true` | Allow snapshots to be used as backup sources. | +| `secondary_target` | `0` | Secondary backup target selector (advanced). | + +All storage nodes of the cluster must be able to reach the configured endpoint, since backups are written +directly from the storage nodes. + +## Creating a Backup + +Backups are created from volume snapshots. Create a snapshot and back it up in one step: ```bash title="Create a snapshot and back it up" {{ cliname }} snapshot add --backup @@ -27,12 +60,16 @@ Alternatively, back up an existing snapshot: ``` The backup runs asynchronously in the background. Simplyblock automatically resolves the snapshot's ancestry chain -and backs up any parent snapshots that have not yet been backed up. +and backs up any parent snapshots that have not yet been backed up, so every backup is incremental against the +previous one. + +Backups of encrypted volumes stay encrypted: the volume's data encryption keys are preserved through the cluster's +key management system and are applied again on restore. !!! important Once a snapshot or its chain is backed up (completed), it can be deleted without impact on the backup itself. -### Listing Backups +## Listing Backups To list all backups in the cluster: @@ -40,44 +77,50 @@ To list all backups in the cluster: {{ cliname }} backup list [--cluster-id ] ``` -This may also reference imported (external) backups taken on another cluster. +The list may also contain imported (external) backups taken on another cluster, see +[Cross-Cluster Backup](#cross-cluster-backup). -### Restoring from a Backup +## Restoring from a Backup Restoring a backup creates a new logical volume with the data reconstructed from the S3 backup chain: ```bash title="Restore a backup" {{ cliname }} backup restore \ - --lvol --pool --cluster-id \ + --lvol --pool \ [--node ] ``` -The `--lvol`, `--pool`, and `--cluster-id` parameters are required. Any node of the cluster can restore any -backup. Without `--node`, the node that took the backup is used. +The `--lvol` and `--pool` parameters are required. The target cluster is derived from the pool. Any node of the +cluster can restore any backup; without `--node`, a node is selected automatically by the regular volume placement. -The restore process downloads and applies each backup in the chain. The new volume is set to a restoring state during -the transfer and transitions to online once complete. +The restore process downloads and applies each backup of the chain, newest first. The new volume is in the +`restoring` state during the transfer and transitions to online once complete. + +A restore is only accepted when every backup in the chain has completed, and when the backup's source cluster +matches the currently active S3 backup source (see [Cross-Cluster Backup](#cross-cluster-backup) for restoring +backups taken on another cluster). !!! warning The restore operation creates a new volume. It does not overwrite or modify any existing volume. !!! note - The restored volume is created with the default high-availability type and NVMe/TCP, regardless of the - settings of the original volume. Deleting the original snapshot or volume does not affect its backups. + The restored volume is created with the cluster's default high-availability type and NVMe/TCP, regardless of + the settings of the original volume. Encryption and the allowed-host list of the original volume are preserved. + Deleting the original snapshot or volume does not affect its backups. -### Deleting Backups +## Deleting Backups -To delete all backups for a specific volume: +To delete all backups for a specific volume, including the backup data in S3: ```bash title="Delete backups for a volume" {{ cliname }} backup delete ``` -### Backup Policies +## Backup Policies Backup policies automate backup creation and retention management. -#### Creating a Policy +### Creating a Policy ```bash title="Create a backup policy" {{ cliname }} backup policy-add \ @@ -89,14 +132,17 @@ Backup policies automate backup creation and retention management. Parameters: -- `--versions`: Maximum number of backup versions to retain (e.g., `10`). -- `--age`: Maximum backup age before cleanup (e.g., `7d`, `12h`, `1w`). +- `--versions`: Maximum number of completed backup versions to retain (e.g., `10`). +- `--age`: Maximum backup age (e.g., `7d`, `12h`, `1w`). - `--schedule`: Tiered backup schedule (e.g., `"15m,4 60m,11 24h,7"`). The schedule format is a space-separated list of `interval,count` pairs. For example, `15m,4 60m,11 24h,7` means: take a backup every 15 minutes (keep 4), every 60 minutes (keep 11), and every 24 hours (keep 7). -#### Attaching a Policy +Retention does not delete data: when a policy's version or age limit is exceeded, the oldest backup is merged +into the next one, so the number of restore points shrinks while the backup chain stays complete. + +### Attaching a Policy Policies can be attached to individual volumes or entire storage pools: @@ -108,7 +154,7 @@ Policies can be attached to individual volumes or entire storage pools: {{ cliname }} backup policy-attach lvol ``` -#### Detaching a Policy +### Detaching a Policy ```bash title="Detach a policy" {{ cliname }} backup policy-detach pool @@ -117,7 +163,7 @@ Policies can be attached to individual volumes or entire storage pools: Detaching a policy does not impact existing backups! -#### Listing and Removing Policies +### Listing and Removing Policies ```bash title="List backup policies" {{ cliname }} backup policy-list [--cluster-id ] @@ -127,11 +173,11 @@ Detaching a policy does not impact existing backups! {{ cliname }} backup policy-remove ``` -### Cross-Cluster Backup +## Cross-Cluster Backup Cross-cluster backup enables restoring data on a different simplyblock cluster using backups stored in S3. -#### Exporting Backup Metadata +### Exporting Backup Metadata Export backup metadata from the source cluster: @@ -144,7 +190,7 @@ Export backup metadata from the source cluster: This produces a JSON file containing backup metadata (not the actual data, which remains in S3). -#### Importing Backup Metadata +### Importing Backup Metadata On the target cluster, import the metadata: @@ -152,7 +198,7 @@ On the target cluster, import the metadata: {{ cliname }} backup import --cluster-id ``` -#### Switching the Backup Source +### Switching the Backup Source Before restoring imported backups, switch the target cluster's S3 source to read from the original cluster's bucket: @@ -161,8 +207,10 @@ bucket: {{ cliname }} backup source-switch [--cluster-id ] ``` -The switch changes only the bucket that is read. The target cluster's own S3 credentials and endpoint are reused, -so they must have access to the source cluster's bucket. To list available backup sources: +The switch changes only the bucket that is read; the target cluster's own S3 credentials and endpoint are reused, +so they must have access to the source cluster's bucket. Attempting to restore an imported backup without +switching the source first is rejected with a message naming the required source. To list available backup +sources: ```bash title="List backup sources" {{ cliname }} backup source-list [--cluster-id ] @@ -172,9 +220,8 @@ so they must have access to the source cluster's bucket. To list available backu While the backup source is switched to an external cluster, new backups cannot be created on the local cluster. Switch back to the local source after completing restore operations. -After switching the source, use the standard `backup restore` command to restore from the imported backups. For a -cross-cluster restore, pass `--node ` explicitly, since the node recorded in the backup belongs to -the source cluster. +After switching the source, use the standard `backup restore` command to restore from the imported backups. The +target node is selected automatically in the target cluster; `--node` may be passed to pin one. Once the restores are complete, switch the source back: @@ -182,226 +229,8 @@ Once the restores are complete, switch the source back: {{ cliname }} backup source-switch local [--cluster-id ] ``` -## Kubernetes CRD Operations - -In Kubernetes environments, backups can be managed declaratively using Custom Resource Definitions (CRDs). This -is especially useful for automated backup workflows integrated with Kubernetes-native tooling. - -### Prerequisites - -#### S3-Compatible Object Storage - -Backups require an S3-compatible object storage endpoint. For local testing, a MinIO instance can be deployed: - -```bash title="Deploy a local MinIO instance for testing" -kubectl create ns minio - -kubectl -n minio create deployment minio \ - --image=minio/minio \ - -- /bin/sh -c "minio server /data --console-address :9001" - -kubectl -n minio expose deploy/minio --port 9000 - -kubectl -n minio set env deploy/minio \ - MINIO_ROOT_USER=minioadmin \ - MINIO_ROOT_PASSWORD=minioadmin123 -``` - -#### Backup Credentials Secret - -Store the S3 credentials in a Kubernetes Secret in the same namespace as the `StorageCluster`: - -```yaml title="Create backup credentials secret" -kubectl apply -f - <<'EOF' -apiVersion: v1 -kind: Secret -metadata: - name: backup-credentials - namespace: simplyblock -type: Opaque -stringData: - access_key_id: - secret_access_key: -EOF -``` - -#### StorageCluster Backup Configuration - -Include a `backup` section in the `StorageCluster` spec referencing the credentials secret: - -```yaml title="StorageCluster backup configuration" -spec: - # ... other fields ... - backup: - credentialsSecretRef: - name: backup-credentials - localEndpoint: http://minio.minio.svc.cluster.local:9000 - snapshotBackups: true - withCompression: false -``` - -See the [Operator Reference](../../../reference/operator/reference.md#storagecluster) for all available `backup` spec fields. - -### StorageBackup CRD - -The `StorageBackup` resource creates a one-time backup of a PVC to the configured S3-compatible storage endpoint. - -```yaml title="Create a backup for a PVC" -kubectl apply -f - <<'EOF' -apiVersion: storage.simplyblock.io/v1alpha1 -kind: StorageBackup -metadata: - name: my-pvc-backup - namespace: simplyblock -spec: - clusterName: simplyblock-cluster - pvcRef: - name: my-pvc -EOF -``` - -Monitor the backup status: - -```bash title="List backups" -kubectl -n simplyblock get storagebackup -``` - -```plain -NAME PHASE PVC BACKUPID SNAPSHOT AGE -my-pvc-backup Done my-pvc 7fab02f8-03f6-4e76-a9ac-78b63b1ce8ef backup-my-pvc-backup 3m -``` - -!!! note - The first backup may take longer to complete as there is no prior incremental state. - -#### Spec Fields - -| Field | Type | Description | -|---------------|--------|--------------------------------------------------| -| `clusterName` | string | Name of the target StorageCluster. **Required**. | -| `pvcRef.name` | string | Name of the PVC to back up. **Required**. | - -#### Status Fields - -| Column | Description | -|------------|-------------------------------------------| -| `PHASE` | Current phase: `InProgress` or `Done`. | -| `PVC` | Name of the source PVC. | -| `BACKUPID` | Backend backup identifier. | -| `SNAPSHOT` | Name of the snapshot used for the backup. | - -### BackupRestore CRD - -The `BackupRestore` resource restores a `StorageBackup` into a new PVC. The restored PVC is created in the -same namespace as the `BackupRestore` object. - -```yaml title="Restore a backup to a new PVC" -kubectl apply -f - <<'EOF' -apiVersion: storage.simplyblock.io/v1alpha1 -kind: BackupRestore -metadata: - name: my-restore - namespace: simplyblock -spec: - clusterName: simplyblock-cluster - backupRef: - name: my-pvc-backup - pvcTemplate: - metadata: - name: restored-pvc - spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 10Gi -EOF -``` - -Monitor the restore status: - -```bash title="List restores" -kubectl -n simplyblock get backuprestore -``` - -```plain -NAME PHASE BACKUP PVC AGE -my-restore Done my-pvc-backup restored-pvc 79s -``` - -The phase transitions from `InProgress` → `PVCBinding` → `Done`. Once `Done`, the new PVC is ready to attach -to a pod. - -#### Spec Fields - -| Field | Type | Description | -|-----------------------------|--------|---------------------------------------------------------------------------------| -| `clusterName` | string | Name of the target StorageCluster. **Required**. | -| `backupRef.name` | string | Name of the `StorageBackup` to restore from. **Required**. | -| `targetPool` | string | Pool to restore into. Defaults to the source backup PVC's pool. | -| `targetNode` | string | Storage node to restore to. Defaults to the node that held the original backup. | -| `pvcTemplate.metadata.name` | string | Name of the new PVC to create. **Required**. | -| `pvcTemplate.spec` | object | PVC spec (accessModes, resources, etc.). | - -!!! warning - A backup can only be restored to the same namespace as the `BackupRestore` object. - -### BackupPolicy CRD - -A `BackupPolicy` defines an automated backup schedule with retention settings. Attach it to a PVC using the -`simplyblock.io/backup-policy` annotation to automatically create `StorageBackup` objects on schedule. - -```yaml title="Create a backup policy" -kubectl apply -f - <<'EOF' -apiVersion: storage.simplyblock.io/v1alpha1 -kind: BackupPolicy -metadata: - name: my-policy - namespace: simplyblock -spec: - clusterName: simplyblock-cluster - maxVersions: 10 - maxAge: "7d" - schedule: "15m,4 60m,11 24h,7" -EOF -``` - -#### Spec Fields - -| Field | Type | Description | -|---------------|--------|-------------------------------------------------------------------| -| `clusterName` | string | Name of the target StorageCluster. **Required**. | -| `maxVersions` | int | Maximum number of backup versions to retain. | -| `maxAge` | string | Maximum backup age before cleanup (e.g., `7d`, `12h`). | -| `schedule` | string | Tiered backup schedule as space-separated `interval,count` pairs. | - -The schedule format is a space-separated list of `interval,count` pairs. For example, `15m,4 60m,11 24h,7` means: -take a backup every 15 minutes (keep the 4 most recent), every 60 minutes (keep 11), and every 24 hours (keep 7). - -#### Attaching a Policy to a PVC - -Apply the `simplyblock.io/backup-policy` annotation to start automatic backups for a PVC: - -```bash title="Attach a backup policy" -kubectl annotate pvc my-pvc -n simplyblock simplyblock.io/backup-policy=my-policy -``` - -The policy will begin creating `StorageBackup` objects automatically. View them with: +## Kubernetes -```bash title="List auto-created backups" -kubectl get storagebackup -n simplyblock -``` - -#### Updating and Detaching Policies - -To switch a PVC to a different policy (detaches from the old policy and attaches to the new one): - -```bash title="Switch to a different policy" -kubectl annotate pvc my-pvc -n simplyblock simplyblock.io/backup-policy=new-policy --overwrite -``` - -To detach a policy from a PVC (existing backups are not deleted): - -```bash title="Detach a backup policy" -kubectl annotate pvc my-pvc -n simplyblock simplyblock.io/backup-policy- -``` +In Kubernetes environments, the same backup engine is managed declaratively through the `StorageBackup`, +`BackupRestore`, `BackupPolicy`, and `BackupImport` custom resources. See +[Backup and Recovery on Kubernetes](../../../kubernetes/operations/data-protection/backup-recovery.md). diff --git a/docs/non-kubernetes/operations/data-protection/control-plane-backup.md b/docs/non-kubernetes/operations/data-protection/control-plane-backup.md new file mode 100644 index 00000000..bbc43cbb --- /dev/null +++ b/docs/non-kubernetes/operations/data-protection/control-plane-backup.md @@ -0,0 +1,85 @@ +--- +title: "Control-Plane Database Backup" +description: "Back up and restore the FoundationDB key-value store behind the simplyblock control plane on plain Linux with the sbctl db-backup commands." +weight: 10530 +--- + +The simplyblock control plane stores all cluster metadata — clusters, nodes, pools, volumes, snapshots, tasks — in +a FoundationDB key-value store on the management nodes. Volume data is not affected by the loss of this database, +but the cluster cannot be managed without it. Simplyblock therefore takes periodic backups of the control-plane +database, which can be written to a local path or to Amazon S3. + +On plain Linux (Docker-based deployments), these backups are managed with the `{{ cliname }} db-backup` commands +described here. On Kubernetes, control-plane backups are handled by the FoundationDB operator instead, see +[FoundationDB Backup and Restore](../../../kubernetes/operations/data-protection/foundationdb-backup.md). + +## Configuring the Backup Destination + +By default, backups are written every three hours to `/etc/foundationdb/backup/` on the management +node. Both the destination and the frequency can be changed: + +```bash title="Configure a local backup path and frequency" +{{ cliname }} db-backup config \ + --backup-path /mnt/backup/fdb \ + --backup-frequency 3h +``` + +```bash title="Configure Amazon S3 as the backup destination" +{{ cliname }} db-backup config \ + --s3-bucket \ + --s3-region \ + --s3-credentials : \ + --backup-frequency 1d +``` + +| Parameter | Default | Description | +|----------------------|----------------------------|--------------------------------------------------------| +| `--backup-path` | `/etc/foundationdb/backup` | Local backup directory on the management node. | +| `--backup-frequency` | `3h` | Interval between automatic backups (e.g., `3h`, `1d`). | +| `--s3-bucket` | — | Amazon S3 bucket name. | +| `--s3-region` | — | Amazon S3 region. | +| `--s3-credentials` | — | S3 API key and secret in the form `KEY:SECRET`. | + +The local path and S3 are mutually exclusive destinations: configuring a local path clears any stored S3 +settings. When S3 is configured, access to the bucket is verified first and the configuration is rejected if the +bucket cannot be listed with the given credentials. + +!!! note + A local backup path only protects against database corruption, not against the loss of the management node. + Place it on storage that is independent of the management node, or use S3. + +## Automatic Backups + +Once configured, the control plane takes a backup automatically whenever the last one is older than the +configured frequency. No further setup is required. Backup creation, restore, and failure events appear in the +cluster event log. + +## Manual Operations + +```bash title="Create a backup now" +{{ cliname }} db-backup create +``` + +```bash title="List available backups" +{{ cliname }} db-backup list +``` + +```bash title="Show the status of the running backup system" +{{ cliname }} db-backup status +``` + +## Restoring the Control-Plane Database + +A restore replaces the complete content of the control-plane database with the backup: + +```bash title="Restore a backup" +{{ cliname }} db-backup restore +``` + +`` is a backup as reported by `db-backup list`. + +!!! danger + The restore first **clears the entire control-plane database** and then loads the backup. All metadata changes + made after the backup was taken are lost — volumes, snapshots, or nodes added since then become unknown to the + control plane, while their data continues to exist on the storage nodes. Only restore the database as part of a + guided disaster recovery, and never while management services are actively modifying the cluster. diff --git a/docs/non-kubernetes/operations/data-protection/index.md b/docs/non-kubernetes/operations/data-protection/index.md index 9b627f6d..4fcf2c79 100644 --- a/docs/non-kubernetes/operations/data-protection/index.md +++ b/docs/non-kubernetes/operations/data-protection/index.md @@ -5,9 +5,11 @@ weight: 10500 --- Data is protected on two levels outside Kubernetes. A logical volume is backed up to S3-compatible object storage as a -chain of snapshots, and its snapshots are replicated to a second cluster, from which a failover can be served. +chain of snapshots, and its snapshots are replicated to a second cluster, from which a failover can be served. The +control-plane database itself is backed up periodically as well. -| Topic | Purpose | -|---------------------------------------------------------|------------------------------------------------------------------------| -| [Backup and Recovery](backup-recovery.md) | Backing up a volume to S3-compatible object storage, and restoring it. | -| [Asynchronous Replication](asynchronous-replication.md) | Replicating snapshots to a second cluster for a failover. | +| Topic | Purpose | +|----------------------------------------------------------|------------------------------------------------------------------------| +| [Backup and Recovery](backup-recovery.md) | Backing up a volume to S3-compatible object storage, and restoring it. | +| [Asynchronous Replication](asynchronous-replication.md) | Replicating snapshots to a second cluster for a failover. | +| [Control-Plane Database Backup](control-plane-backup.md) | Backing up and restoring the control plane's FoundationDB metadata. |