Backup Classes

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:

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:

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

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:

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:

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 for the full Plan / BackupJob / RestoreJob walkthrough and Virtualization backup and recovery for the VM-side flow.