Skip to content

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.

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

Open
Andrey Kolkov (androndo) wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix(backup): simplify UX with default backupclass #547

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
25 changes: 12 additions & 13 deletions content/en/docs/next/applications/backup-and-recovery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,11 @@ weight: 4
This guide covers backing up and restoring **Cozystack-managed databases** — Postgres, MariaDB, and ClickHouse — as a tenant user: running one-off and scheduled backups, checking status, and restoring from a backup either in place or into a separate target instance.

{{% alert color="info" %}}
**Storage, credentials, and the `BackupClass` are admin-provisioned.** Before you can run a `BackupJob`, an administrator provisions the S3 storage and the per-application credential Secrets your driver expects, and creates the cluster-scoped `BackupClass` you reference. Ask your administrator for:
**Storage and the `BackupClass` are platform-provisioned.** Cozystack ships a single cluster-scoped `BackupClass` named `cozy-default` that covers Postgres, MariaDB, ClickHouse, Etcd, VMInstance, and VMDisk via a per-Kind `strategies[]` array. You reference it by name from `BackupJob` / `Plan` / `RestoreJob` — there is no per-application `BackupClass`, and you do **not** create or supply S3 credentials, endpoints, or paths. The platform projects a credentials Secret (`cozy-backups-creds`) into your tenant namespace automatically right before each BackupJob runs.

- the `BackupClass` name to use for your application Kind (you cannot list `BackupClass` resources under your tenant kubeconfig — they are cluster-scoped);
- confirmation that the per-application credential Secrets exist in your namespace for every managed-DB application you want to back up.
If your administrator has created additional sibling `BackupClass` resources (different retention, different storage, etc.), ask for the name and substitute it for `cozy-default` in the examples below. `BackupClass` is cluster-scoped, so you cannot list it under a tenant kubeconfig — your administrator will tell you which names are valid.

Admins follow the [Managed Application Backup Configuration]({{% ref "/docs/next/operations/services/managed-app-backup-configuration" %}}) guide.
Admins follow the [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) guide.
{{% /alert %}}

{{% alert color="warning" %}}
Expand All @@ -28,8 +27,8 @@ For backups that include the application's Helm release, CRs, and PVC snapshots

## Prerequisites

- A `BackupClass` name handed to you by your administrator (for example, `postgres-data-backup` for a `Postgres` application).
- An existing managed-DB application (`Postgres`, `MariaDB`, or `ClickHouse`) in your tenant namespace.
- A `BackupClass` name. On a default install this is `cozy-default`, which covers `Postgres`, `MariaDB`, `ClickHouse`, and `Etcd`. If your administrator has created a sibling class, substitute that name everywhere below.
- An existing managed-DB application (`Postgres`, `MariaDB`, `ClickHouse`, or `Etcd`) in your tenant namespace.
- `kubectl` and a tenant kubeconfig with the `tenant-<ns>-admin` role.

The examples below assume `tenant-user` for the tenant namespace; substitute your own.
Expand All @@ -51,7 +50,7 @@ spec:
apiGroup: apps.cozystack.io
kind: Postgres
name: my-postgres
backupClassName: postgres-data-backup
backupClassName: cozy-default
```

```bash
Expand All @@ -62,7 +61,7 @@ kubectl -n tenant-user describe backupjob my-postgres-adhoc

When the `BackupJob` reaches `phase: Succeeded`, the driver creates a `Backup` object with the same name. That name is what you reference when restoring.

Replace `Postgres` / `postgres-data-backup` with `MariaDB` / `mariadb-data-backup` or `ClickHouse` / `clickhouse-data-backup` for the other drivers.
Replace `Postgres` with `MariaDB`, `ClickHouse`, or `Etcd` for the other drivers — the `BackupClass` (`cozy-default`) is the same; the platform-shipped class binds a strategy for every supported Kind.

### Scheduled backup

Expand All @@ -79,7 +78,7 @@ spec:
apiGroup: apps.cozystack.io
kind: Postgres
name: my-postgres
backupClassName: postgres-data-backup
backupClassName: cozy-default
schedule:
type: cron
cron: "0 */6 * * *" # every 6 hours
Expand Down Expand Up @@ -110,7 +109,7 @@ kubectl -n tenant-user describe backupjob my-postgres-adhoc
kubectl -n tenant-user get events --field-selector involvedObject.name=my-postgres-adhoc
```

If `status.message` does not pinpoint the failure, hand the `BackupJob` name to your administrator and they will inspect the operator-native CR the driver created (see [Tenant escalation: driver-side diagnostics]({{% ref "/docs/next/operations/services/managed-app-backup-configuration#tenant-escalation-driver-side-diagnostics" %}}) in the admin guide).
If `status.message` does not pinpoint the failure, hand the `BackupJob` name to your administrator and they will inspect the operator-native CR the driver created (see [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) in the admin guide).

## Restore in place

Expand Down Expand Up @@ -201,10 +200,10 @@ kubectl -n tenant-user describe backupjob my-postgres-adhoc
kubectl -n tenant-user get events --field-selector involvedObject.name=my-postgres-adhoc
```

If those do not explain the failure, the next layer of diagnostics lives on the operator-native CR the driver created (`cnpg.io/Backup`, `k8s.mariadb.com/Backup`, or the ClickHouse strategy `Pod` logs). These resources are not reachable under the tenant kubeconfig — hand the `BackupJob` name to your administrator and they will follow [Tenant escalation: driver-side diagnostics]({{% ref "/docs/next/operations/services/managed-app-backup-configuration#tenant-escalation-driver-side-diagnostics" %}}).
If those do not explain the failure, the next layer of diagnostics lives on the operator-native CR the driver created (`cnpg.io/Backup`, `k8s.mariadb.com/Backup`, or the ClickHouse strategy `Pod` logs). These resources are not reachable under the tenant kubeconfig — hand the `BackupJob` name to your administrator and they will follow [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}).

## See also

- [Managed Application Backup Configuration]({{% ref "/docs/next/operations/services/managed-app-backup-configuration" %}}) — how administrators define strategies and `BackupClass` resources.
- [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) — how administrators define strategies and `BackupClass` resources.
- [Backup and Recovery (VMs)]({{% ref "/docs/next/virtualization/backup-and-recovery" %}}) — the parallel guide for VMInstance / VMDisk backups (HelmRelease + CRs + PVC snapshots).
- [Velero Backup Configuration]({{% ref "/docs/next/operations/services/velero-backup-configuration" %}}) — administrator setup for the Velero-driven VM backups.
- [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) — administrator setup for the Velero-driven VM backups.
Comment on lines +207 to +209

@gemini-code-assist gemini-code-assist Bot May 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

medium

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.

Suggested change
- [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) — how administrators define strategies and `BackupClass` resources.
- [Backup and Recovery (VMs)]({{% ref "/docs/next/virtualization/backup-and-recovery" %}}) — the parallel guide for VMInstance / VMDisk backups (HelmRelease + CRs + PVC snapshots).
- [Velero Backup Configuration]({{% ref "/docs/next/operations/services/velero-backup-configuration" %}}) — administrator setup for the Velero-driven VM backups.
- [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) — administrator setup for the Velero-driven VM backups.
- [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) — how administrators define strategies and BackupClass resources.
- [Backup and Recovery (VMs)]({{% ref "/docs/next/virtualization/backup-and-recovery" %}}) — the parallel guide for VMInstance / VMDisk backups (HelmRelease + CRs + PVC snapshots).

2 changes: 1 addition & 1 deletion content/en/docs/next/applications/clickhouse.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ It is used for online analytical processing (OLAP).
### How to restore backup from S3

{{% alert color="warning" %}}
**Backups: prefer the `BackupClass` flow.** `backup.enabled` and the S3 fields (`s3Region`, `s3Bucket`, `endpoint`, `s3PathOverride`, `s3AccessKey`/`s3SecretKey` or `s3CredentialsSecret`) are still required — they materialise the in-pod `clickhouse-backup` sidecar that the Altinity backup strategy talks to. However, `backup.schedule`, `backup.cleanupStrategy`, and `backup.resticPassword` (which drive the legacy chart-managed CronJob doing dump + restic, and the matching restic restore flow documented below) are **superseded** by the Cozystack backups framework: define a `BackupClass` + `Altinity` strategy once, then drive scheduled backups via `Plan` and restores via `RestoreJob`. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Managed Application Backup Configuration]({{% ref "/docs/next/operations/services/managed-app-backup-configuration" %}}) (admin setup).
**Backups: prefer the `BackupClass` flow.** `backup.enabled` and the S3 fields (`s3Region`, `s3Bucket`, `endpoint`, `s3PathOverride`, `s3AccessKey`/`s3SecretKey` or `s3CredentialsSecret`) are still required — they materialise the in-pod `clickhouse-backup` sidecar that the Altinity backup strategy talks to. However, `backup.schedule`, `backup.cleanupStrategy`, and `backup.resticPassword` (which drive the legacy chart-managed CronJob doing dump + restic, and the matching restic restore flow documented below) are **superseded** by the Cozystack backups framework: define a `BackupClass` + `Altinity` strategy once, then drive scheduled backups via `Plan` and restores via `RestoreJob`. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) (admin setup).

@coderabbitai coderabbitai Bot Jun 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

This update must be applied upstream, not in the generated doc.

Line 24 changes a file marked autogenerated (Line 12). Please edit the upstream application README and regenerate docs; direct edits here are non-durable.

As per coding guidelines: “Autogenerated files from cozystack/cozystack … To change the body, edit the upstream README … then re-run the corresponding make update-* target.”

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@content/en/docs/next/applications/clickhouse.md` at line 24, This change was
made in an autogenerated file (clickhouse.md) and must be applied upstream: edit
the application's README in the cozystack/cozystack repo to update the Backup
guidance (replace legacy backup.schedule, backup.cleanupStrategy,
backup.resticPassword text with the new BackupClass + Altinity strategy
instructions referencing Plan and RestoreJob), then regenerate docs by running
the corresponding make update-* target so the change propagates into the
generated content; do not edit the generated clickhouse.md directly.

{{% /alert %}}

1. Find the snapshot:
Expand Down
2 changes: 1 addition & 1 deletion content/en/docs/next/applications/mariadb.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ more details:

### Backup parameters
{{% alert color="warning" %}}
**The chart-level `backup.*` values documented below are deprecated.** The legacy `mariadb-dump` + `restic` flow is superseded by the Cozystack backups framework: define a `BackupClass` + `MariaDB` strategy once, then drive backups via `BackupJob` / `Plan` and restores via `RestoreJob`. Existing tenants with `backup.enabled=true` continue to render the legacy resources unchanged. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Managed Application Backup Configuration]({{% ref "/docs/next/operations/services/managed-app-backup-configuration" %}}) (admin setup).
**The chart-level `backup.*` values documented below are deprecated.** The legacy `mariadb-dump` + `restic` flow is superseded by the Cozystack backups framework: define a `BackupClass` + `MariaDB` strategy once, then drive backups via `BackupJob` / `Plan` and restores via `RestoreJob`. Existing tenants with `backup.enabled=true` continue to render the legacy resources unchanged. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) (admin setup).

@coderabbitai coderabbitai Bot Jun 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Move this change to the upstream source and regenerate.

Line 114 modifies an autogenerated file (see Line 11), so this edit should be done in the source README under cozystack/cozystack and then synced via the update target.

As per coding guidelines: “Autogenerated files from cozystack/cozystack … To change the body, edit the upstream README … then re-run the corresponding make update-* target.”

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@content/en/docs/next/applications/mariadb.md` at line 114, Revert the edit in
the autogenerated file and instead add the deprecation note to the upstream
README in the cozystack/cozystack repository (the bold line starting "**The
chart-level `backup.*` values documented below are deprecated.**") so the source
contains the new text, then run the appropriate make update-* target to
regenerate this file; ensure the upstream README change preserves the same
wording and the existing refs to Application Backup and Recovery and Backup
Classes so the regenerated doc includes the updated paragraph.

{{% /alert %}}

| Name | Description | Type | Value |
Expand Down
2 changes: 1 addition & 1 deletion content/en/docs/next/applications/postgres.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ This managed service is controlled by the CloudNativePG operator, ensuring effic
## Operations

{{% alert color="warning" %}}
**Backups: prefer the `BackupClass` flow.** The chart-level `backup.*` values documented below still configure the Barman object store and S3 credentials that backups read from, but the chart-emitted `ScheduledBackup` and the `bootstrap`-based recovery flow have been **superseded** by the Cozystack backups framework: define a `BackupClass` + `CNPG` strategy once, then drive scheduled backups via `Plan` and restores via `RestoreJob`. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Managed Application Backup Configuration]({{% ref "/docs/next/operations/services/managed-app-backup-configuration" %}}) (admin setup).
**Backups: prefer the `BackupClass` flow.** The chart-level `backup.*` values documented below still configure the Barman object store and S3 credentials that backups read from, but the chart-emitted `ScheduledBackup` and the `bootstrap`-based recovery flow have been **superseded** by the Cozystack backups framework: define a `BackupClass` + `CNPG` strategy once, then drive scheduled backups via `Plan` and restores via `RestoreJob`. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) (admin setup).

@coderabbitai coderabbitai Bot Jun 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Do not edit autogenerated application docs in-place.

This file declares itself autogenerated (Line 11), so Line 31 should be changed in the upstream source README and regenerated; otherwise the change will be lost on next sync.

As per coding guidelines: “Autogenerated files from cozystack/cozystack … To change the body, edit the upstream README … then re-run the corresponding make update-* target.”

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@content/en/docs/next/applications/postgres.md` at line 31, The change was
made in an autogenerated file (see the autogenerated declaration at the top) so
do not edit content/en/docs/next/applications/postgres.md directly; instead edit
the upstream README entry that contains the paragraph starting "Backups: prefer
the `BackupClass` flow." in the cozystack/cozystack source, then regenerate the
docs by running the appropriate make update-* target so the updated text is
propagated into the generated postgresql application doc.

{{% /alert %}}

### How to enable backups
Expand Down
4 changes: 2 additions & 2 deletions content/en/docs/next/kubernetes/backups-with-velero-addon.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The `velero` addon of the [Managed Kubernetes]({{% ref "/docs/next/kubernetes" %
{{% alert color="info" %}}
This guide is for the **tenant-side** Velero addon, which runs inside a tenant Kubernetes cluster and is operated by the tenant user.

For the platform-level Velero used by cluster administrators to back up `VMInstance`/`VMDisk` resources from the management cluster, see [Velero Backup Configuration]({{% ref "/docs/next/operations/services/velero-backup-configuration" %}}).
For the platform-level Velero used by cluster administrators to back up `VMInstance`/`VMDisk` resources from the management cluster, see [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}).
{{% /alert %}}

## What the addon installs
Expand Down Expand Up @@ -172,4 +172,4 @@ The same pattern restores into a **different** tenant Kubernetes cluster as well

- [Managed Kubernetes — `addons.velero` parameters]({{% ref "/docs/next/kubernetes#parameters" %}})
- [Buckets and Users]({{% ref "/docs/next/operations/services/object-storage/buckets" %}})
- [Velero Backup Configuration (platform admin)]({{% ref "/docs/next/operations/services/velero-backup-configuration" %}})
- [Backup Classes (platform admin)]({{% ref "/docs/next/operations/services/backup-classes" %}})
Loading