|
| 1 | +--- |
| 2 | +title: "Platform-Managed Backups in Cozystack" |
| 3 | +slug: platform-managed-backups-in-cozystack |
| 4 | +date: 2026-05-31 |
| 5 | +author: "Timur Tukaev" |
| 6 | +description: "Cozystack introduces platform-managed backups: tenants declare what to protect, the platform handles where and how. One-shot jobs, scheduled plans, and point-in-time restore for Postgres, MariaDB, ClickHouse, and KubeVirt VMs." |
| 7 | +images: |
| 8 | + - "social-card.png" |
| 9 | +article_types: |
| 10 | + - how-to |
| 11 | +topics: |
| 12 | + - platform |
| 13 | + - backup |
| 14 | +--- |
| 15 | + |
| 16 | +Backups are everyone's responsibility and, too often, nobody's job. On a multi-tenant platform the problem is sharper: tenants want to protect their own databases and VMs, but they shouldn't be handed S3 credentials or asked to wire up storage. Cozystack closes that gap with **platform-managed backups** — a clear API where tenants declare **what** to protect and the platform takes care of **where** and **how**. |
| 17 | + |
| 18 | +## The model in one minute |
| 19 | + |
| 20 | +There are five objects, split cleanly between two audiences. |
| 21 | + |
| 22 | +Tenant-facing: |
| 23 | + |
| 24 | +- **BackupJob** — a one-off backup. |
| 25 | +- **Plan** — scheduled (cron) backups. |
| 26 | +- **Backup** — represents the artifact produced by a BackupJob. |
| 27 | +- **RestoreJob** — restores a backup into a target application. |
| 28 | + |
| 29 | +{{< figure src="1.png" alt="Diagram of the five backup API objects and their relationships" width="720" >}} |
| 30 | + |
| 31 | +Admin-owned: |
| 32 | + |
| 33 | +- **BackupClass** — binds an application Kind to a backup strategy and storage, and tunes desired parameters. |
| 34 | + |
| 35 | +Tenants reference a `BackupClass` by name and never see S3 endpoints, credentials, paths, or underlying resources — those are accessible to cluster administrators only. The platform performs backups in a managed way and guarantees robustness and stability. |
| 36 | + |
| 37 | +Cozystack ships a predefined class `cozy-default` and a storage bucket `cozy-backups` — no configuration needed to get started. |
| 38 | + |
| 39 | +{{< figure src="2.png" alt="BackupClass object showing the admin-controlled binding between application Kind, strategy, and storage" width="720" >}} |
| 40 | + |
| 41 | +## For tenant users: back up and restore your apps |
| 42 | + |
| 43 | +The `cozy-default` BackupClass is provisioned automatically and already covers Postgres, MariaDB, ClickHouse, Etcd, and KubeVirt VMs (`VMInstance`, `VMDisk`). You only need to select your application — no configuration or storage setup required. |
| 44 | + |
| 45 | +{{< figure src="3.png" alt="Cozystack dashboard showing the BackupJob creation form for a Postgres application" width="720" >}} |
| 46 | + |
| 47 | +{{< figure src="4.png" alt="BackupJob status showing phase Succeeded with backup artifact details" width="720" >}} |
| 48 | + |
| 49 | +We recommend starting with a one-shot `BackupJob` to verify correct operation before setting up a scheduled Plan. |
| 50 | + |
| 51 | +```yaml |
| 52 | +apiVersion: backups.cozystack.io/v1alpha1 |
| 53 | +kind: BackupJob |
| 54 | +metadata: |
| 55 | + name: oneshot-mariadb |
| 56 | + namespace: tenant-user1 |
| 57 | +spec: |
| 58 | + applicationRef: |
| 59 | + apiGroup: apps.cozystack.io |
| 60 | + kind: MariaDB |
| 61 | + name: mariadbinstance |
| 62 | + backupClassName: cozy-default |
| 63 | +``` |
| 64 | +
|
| 65 | +Use `Plan` for recurring backups: |
| 66 | + |
| 67 | +{{< figure src="5.png" alt="Cozystack dashboard showing the Plan creation form with cron schedule configuration" width="720" >}} |
| 68 | + |
| 69 | +{{< figure src="6.png" alt="Plan list view showing active scheduled backup plans and their last run status" width="720" >}} |
| 70 | + |
| 71 | +```yaml |
| 72 | +apiVersion: backups.cozystack.io/v1alpha1 |
| 73 | +kind: Plan |
| 74 | +metadata: |
| 75 | + name: maria-nightly-backups |
| 76 | + namespace: tenant-user1 |
| 77 | +spec: |
| 78 | + applicationRef: |
| 79 | + apiGroup: apps.cozystack.io |
| 80 | + kind: MariaDB |
| 81 | + name: mariadbinstance |
| 82 | + backupClassName: cozy-default |
| 83 | + schedule: |
| 84 | + type: cron |
| 85 | + cron: "0 2 * * *" # at 02:00 |
| 86 | +``` |
| 87 | + |
| 88 | +Once a BackupJob reaches `phase: Succeeded`, you can restore from it: |
| 89 | + |
| 90 | +{{< figure src="7.png" alt="RestoreJob creation form with source backup and target application configured" width="720" >}} |
| 91 | + |
| 92 | +Restoring comes in two flavors. A `RestoreJob` either replays into the same application (**in-place** — fast rollback, but destructive) or into a freshly provisioned copy of the same Kind (**to-copy** — safe for DR drills and validation). You choose by whether you set `targetApplicationRef`. |
| 93 | + |
| 94 | +## For cluster admins: defaults, tuning, and opt-ins |
| 95 | + |
| 96 | +For most platforms, `cozy-default` ships ready and your tenants can back up immediately without any setup. |
| 97 | + |
| 98 | +{{< figure src="8.png" alt="BackupClass manifest showing strategy, storage binding, and retention configuration" width="720" >}} |
| 99 | + |
| 100 | +Reach for a custom `BackupClass` when you need to: |
| 101 | + |
| 102 | +- **tune retention** for a specific application or tenant; |
| 103 | +- **enable a new Kind** not bound by default; |
| 104 | +- **use a dedicated bucket** — split storage for simplified maintenance. |
| 105 | + |
| 106 | +## Going further: custom strategies |
| 107 | + |
| 108 | +The backups API is extensible. If a driver you need doesn't exist yet, you have two routes: |
| 109 | + |
| 110 | +- **No code:** the generic Job-based strategy. Reuse a plain Kubernetes Job as the backup mechanism — useful for bespoke or self-managed workloads. See the [NATS example](https://github.com/cozystack/cozystack/blob/main/examples/backups/nats/01-create-strategy.sh). |
| 111 | +- **A custom strategy controller** built against the backups API and embedded in Cozystack, for first-class lifecycle handling. |
| 112 | + |
| 113 | +## Learn more |
| 114 | + |
| 115 | +- [Application Backup and Recovery](https://cozystack.io/docs/v1.4/applications/backup-and-recovery/) |
| 116 | +- [Backup Classes — admin guide](https://cozystack.io/docs/v1.4/operations/services/backup-classes/) |
| 117 | +- [More examples](https://github.com/cozystack/cozystack/tree/main/examples/backups) |
| 118 | + |
| 119 | +## Join the community |
| 120 | + |
| 121 | +- [GitHub](https://github.com/cozystack/cozystack) |
| 122 | +- Telegram [group](https://t.me/cozystack) |
| 123 | +- Slack [group](https://kubernetes.slack.com/archives/C06L3CPRVN1) (get invite at [https://slack.kubernetes.io](https://slack.kubernetes.io)) |
| 124 | +- [Community Meeting Calendar](https://calendar.google.com/calendar?cid=ZTQzZDIxZTVjOWI0NWE5NWYyOGM1ZDY0OWMyY2IxZTFmNDMzZTJlNjUzYjU2ZGJiZGE3NGNhMzA2ZjBkMGY2OEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t) |
0 commit comments