-
Notifications
You must be signed in to change notification settings - Fork 29
fix(backup): simplify UX with default backupclass #547
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.
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
Open
androndo
wants to merge
1
commit into
main
Choose a base branch
from
feat/backup-default-class
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
100 changes: 100 additions & 0 deletions
100
content/en/docs/next/operations/services/backup-classes.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| --- | ||
| title: "Backup Classes" | ||
| linkTitle: "Backup Classes" | ||
| description: "Default cozy-default BackupClass and the parameters tenants and admins can tune." | ||
| weight: 31 | ||
| --- | ||
|
|
||
| Cozystack ships a single platform-managed `BackupClass` named `cozy-default`. It is provisioned automatically when the `backupstrategy-controller` chart is installed and references the system-managed S3 bucket `cozy-backups` in the `cozy-backup-controller` namespace. | ||
|
|
||
| Tenants reference `cozy-default` from `BackupJob`, `Plan`, and `RestoreJob` resources — they do **not** supply S3 credentials, endpoints, or paths. The platform projects the system-managed credentials Secret into the tenant namespace per BackupJob (or, for long-lived references like Velero's `BackupStorageLocation`, into a fixed list of system namespaces on a periodic tick), and the default strategy templates encode `<namespace>/<application>` into every S3 path so two tenants with the same application name never collide. | ||
|
|
||
| ## Supported applications | ||
|
|
||
| The default BackupClass binds one strategy per managed Kind: | ||
|
|
||
| | Application Kind | Driver | Strategy CR | | ||
| |------------------|--------|-------------| | ||
| | `apps.cozystack.io/Postgres` | CloudNativePG (barman) | `strategy.backups.cozystack.io/CNPG` `cozy-default-cnpg` | | ||
| | `apps.cozystack.io/MariaDB` | mariadb-operator dump | `strategy.backups.cozystack.io/MariaDB` `cozy-default-mariadb` | | ||
| | `apps.cozystack.io/ClickHouse` | Altinity `clickhouse-backup` sidecar | `strategy.backups.cozystack.io/Altinity` `cozy-default-altinity` | | ||
| | `apps.cozystack.io/Etcd` | etcd-operator snapshot | `strategy.backups.cozystack.io/Etcd` `cozy-default-etcd` | | ||
| | `apps.cozystack.io/FoundationDB` | FoundationDB operator backup_agent | `strategy.backups.cozystack.io/FoundationDB` `cozy-default-foundationdb` | | ||
| | `apps.cozystack.io/VMInstance` | Velero + kubevirt-velero-plugin | `strategy.backups.cozystack.io/Velero` `cozy-default-velero-vminstance` | | ||
| | `apps.cozystack.io/VMDisk` | Velero | `strategy.backups.cozystack.io/Velero` `cozy-default-velero-vmdisk` | | ||
|
|
||
| VM-driven (Velero) backups land in the same `cozy-backups` bucket under the `velero/` prefix. A `BackupStorageLocation` named `cozy-default` is shipped by the `velero` chart and consumes the platform credentials from the `cozy-backups-creds` Secret in `cozy-velero` (refreshed by the `SystemCredentialsProjector` runnable in the backupstrategy-controller). | ||
|
|
||
| ## ClickHouse: opt-in to the system bucket | ||
|
|
||
| The `clickhouse-backup` sidecar runs inside the ClickHouse Pod itself, so the Helm chart is what wires its S3 credentials. Existing tenants on the legacy `backup.s3*` values continue to work unchanged. To switch a release onto the platform bucket, set: | ||
|
|
||
| ```yaml | ||
| backup: | ||
| enabled: true | ||
| useSystemBucket: true | ||
| ``` | ||
|
|
||
| When `useSystemBucket: true`: | ||
|
|
||
| - The chart-emitted `<release>-backup-s3` Secret is no longer rendered. | ||
| - The sidecar consumes `cozy-backups-creds` (projected by the platform). | ||
| - `S3_PATH` is set to `<namespace>/<release>` so two tenants with the same ClickHouse release name never share a prefix. | ||
|
|
||
| `s3Region`, `s3Bucket`, `endpoint`, `s3AccessKey`, `s3SecretKey`, and `s3CredentialsSecret` are ignored in this mode. | ||
|
|
||
| ## Inspecting the defaults | ||
|
|
||
| ```bash | ||
| kubectl get backupclasses | ||
| kubectl get backupclass cozy-default -o yaml | ||
| kubectl -n cozy-backup-controller get bucket cozy-backups | ||
| kubectl -n cozy-backup-controller get secret cozy-backups-system-credentials | ||
| kubectl -n cozy-velero get backupstoragelocation cozy-default | ||
| ``` | ||
|
|
||
| The bucket lives in `cozy-backup-controller` and is provisioned through the `apps.cozystack.io/Bucket` CR; the system-managed credentials Secret never leaves that namespace. The backupstrategy-controller projects a copy under the name `cozy-backups-creds` into a tenant namespace right before each BackupJob runs, and refreshes the same Secret in `cozy-velero` (and any other namespace listed in `backupStorage.systemNamespaces`) on a 1-minute tick. The projected Secret carries multiple key formats so each driver finds what it needs in one place: | ||
|
|
||
| | Key | Consumer | | ||
| |-----|----------| | ||
| | `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | CNPG, MariaDB, Etcd | | ||
| | `accessKey` / `secretKey` (plus `bucketName`, `endpoint`, `region`) | ClickHouse sidecar | | ||
| | `cloud` | Velero (AWS credentials file format) | | ||
| | `blob_credentials.json` | FoundationDB backup_agent | | ||
|
|
||
| ## Tuning via custom BackupClass | ||
|
|
||
| The defaults aim at a reasonable middle (30-day retention, gzip compression where applicable). To override for a specific tenant or workload, create your own `BackupClass` pointing at the same strategy CRs but with tweaked `parameters`, or a fresh strategy CR. Common knobs: | ||
|
|
||
| - **CNPG strategy**: `barmanObjectStore.retentionPolicy`, `data.compression`, `wal.compression`. | ||
| - **MariaDB strategy**: `compression`, `maxRetention`, `databases[]`. | ||
| - **Altinity strategy**: tune the `clickhouse-backup` sidecar via `backup.*` values on the ClickHouse release; the strategy Pod is a thin HTTP client. | ||
| - **FoundationDB strategy**: `snapshotPeriodSeconds`, `agentCount`, `urlParameters[]`. | ||
| - **Velero strategy (VMInstance / VMDisk)**: `ttl`, `includedResources[]`, `excludedResources[]`. | ||
| - **Etcd strategy**: today the strategy is path-only; combine with `Plan.spec.retentionPolicy` for trim cadence. | ||
|
|
||
| The system-managed credentials Secret is the **only** way for in-cluster strategies to reach `cozy-backups`. Do not embed access keys in `BackupClass.parameters` — the security model relies on Secret references, and `parameters` end up in `Backup.status.underlyingResources`, which tenants can read. | ||
|
|
||
| ## Disabling the platform-managed bucket | ||
|
|
||
| If a deployment runs against an external S3 (no SeaweedFS), set `backupStorage.provisionBucket: false` in the `backupstrategy-controller` values and create the `cozy-backups-system-credentials` Secret in `cozy-backup-controller` manually with `accessKey`/`secretKey` fields. Update `backupStorage.endpoint`, `backupStorage.region`, and (for VM backups) the Velero chart's `configuration.backupStorageLocation` to point at the external S3. | ||
|
|
||
| ## Tenant workflow | ||
|
|
||
| Tenants only ever see the BackupClass name. Typical apply: | ||
|
|
||
| ```yaml | ||
| apiVersion: backups.cozystack.io/v1alpha1 | ||
| kind: BackupJob | ||
| metadata: | ||
| name: ad-hoc | ||
| namespace: tenant-acme | ||
| spec: | ||
| backupClassName: cozy-default | ||
| applicationRef: | ||
| apiGroup: apps.cozystack.io | ||
| kind: Postgres | ||
| name: orders-db | ||
| ``` | ||
|
|
||
| See [Applications backup and recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) for the full Plan / BackupJob / RestoreJob walkthrough and [Virtualization backup and recovery]({{% ref "/docs/next/virtualization/backup-and-recovery" %}}) for the VM-side flow. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The 'See also' section now contains two identical links to the 'Backup Classes' guide. Since the new guide covers both managed applications and general backup class configuration, these links should be merged to avoid redundancy.