Cozystack Backups API and implementation

Design doc

The initial design doc can be found here

Tasks

Completed

The core API is implemented by the following PRs:

• [backups] Implement core backup Plan controller #1640
• [backups] Build and deploy backup controller #1685
• [backups] Add indices to core backup resources #1719

The reference strategy implementation is also complete:

• [backups] Scaffold a backup strategy API group #1687
• [backups] Stub the Job backup strategy controller #1720
• feat(backups): implement Job backup strategy #1721 (merged 2026-05-27)

State of the strategy track as of 2026-08-03

Six of the seven drivers now ship a default Strategy CR and are routed by the platform cozy-default BackupClass (packages/system/backupstrategy-controller/templates/backupclass-default.yaml, mirrored in docs/operations/backup-classes.md): Postgres via cozy-default-cnpg, MariaDB via cozy-default-mariadb, Etcd via cozy-default-etcd, ClickHouse via cozy-default-altinity, VMInstance via cozy-default-velero-vminstance and VMDisk via cozy-default-velero-vmdisk.

Two gaps remain on this track, both deliberate rather than forgotten:

• FoundationDB ships strategy-foundationdb-default.yaml but is not bound into cozy-default, because restore runs fdbrestore inside the operator pod and cozy-foundationdb-operator does not mount the projected cozy-backups-creds, so a platform-default FDB restore would fail silently. Wiring that Secret into the operator deployment is what unblocks the binding.
• The generic Job driver landed but ships no default Strategy CR, so it is bring-your-own only.

TODO

The various types of storage refs need to be implemented and the contracts between the various controllers need to be described. Example contract for the reference strategy above may be:

The job driver executes a script that streams a tarball to a well-known location in a pod's volume. Any storage driver runs as a sidecar in the same pod, watches the filesystem at the well-known location. The incoming tarball is passed on to the backend for storing the backups (S3, NFS, Cozystack bucket, etc).

• Formalize the contract
• Generalize it sufficiently to be applicable for various strategies

PVCs are a special case. Contemporary solutions such as velero+kopia deliver unsatisfactory performance. ZFS snapshots can be leveraged to increase efficiency, doing, e.g.

• Weekly full backups of a volume
• Daily incremental backups from snapshots

However, this requires subsequent backups to be "aware" of previously existing backups (i.e. for series of snapshots to be linked to their base backup).

• Design a structure for the metadata
  • The shape of its structs, data types, etc
  • How is it stored
  • How is it discovered
  • How is it referenced in the CRs stored in K8s
• Design a procedure for backing up volumes
  • Proof of concept with a script that can back up a ZFS-backed PVC
  • Proof of concept with a script that can save an incremental backup
  • Proof of concept with a script that can download the base backup, the incremental backups, and reconstruct the PVC in a cluster
  • Additional feature: use all of the above, then rebuild a KubeVirt DataVolume from the PVC restored from a backup and relaunch a VM
• Automate all of the above

TBC