Skip to content

Commit 907281d

Browse files
committed
Reframe retention authority as user-declared, not platform-imposed
Reviewers read "the platform is the single authority that decides when a Backup is removed" as the provider deleting a tenant's backups on its own, which contradicts the user-controlled intent of cozystack/cozystack#3965. Rewords the Overview, Goals, and cleanup contract so the source of truth is the tenant-authored BackupRetentionPolicy enforced by one mechanism, and states explicitly that retention is opt-in: a Backup under no policy is never deleted, with minCount as a floor. Assisted-by: LLM Signed-off-by: Andrey Kolkov <[email protected]>
1 parent aed57a8 commit 907281d

1 file changed

Lines changed: 4 additions & 4 deletions

File tree

‎design-proposals/backup-retention/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
Cozystack's backup subsystem (`backups.cozystack.io/v1alpha1`: `Plan`, `BackupJob`, `Backup`, `RestoreJob`, `BackupClass`) schedules and records backups but never removes them. Retention is delegated per strategy to the underlying operator, and only CNPG, MariaDB, and Velero expose any knob for it; ClickHouse, MongoDB, etcd, FoundationDB, and Job strategies get no age- or count-based cleanup at all, so their artifacts accumulate in object storage until a tenant deletes them by hand. There is no "keep the last N backups" control anywhere in the API.
1111

12-
This proposal introduces a namespaced CRD, `BackupRetentionPolicy`, carrying three orthogonal knobs — `minCount` (a floor), `maxCount` (a ceiling), and `maxAge` (a TTL) — and makes the platform, not the application operator, the single authority that decides when a `Backup` is removed. A `Backup` joins a policy through one label; that label is stamped from a `retentionPolicyName` field shared by `Plan`, `BackupJob`, and `BackupClass`, the last acting as the namespace default. Enumeration and pruning of `Backup` objects live in a core controller, and physical reclamation of the object-store artifact is delegated to the strategy driver, exactly as the Velero path already turns a `Backup` deletion into a `DeleteBackupRequest`. This closes [cozystack/cozystack#3965](https://github.com/cozystack/cozystack/issues/3965).
12+
This proposal introduces a namespaced CRD, `BackupRetentionPolicy`, carrying three orthogonal knobs — `minCount` (a floor), `maxCount` (a ceiling), and `maxAge` (a TTL) — and makes the user's own `BackupRetentionPolicy` the single source of truth for retention: one visible, tenant-authored policy rather than each operator's hidden native TTL. Retention is opt-in — a `Backup` under no policy is never deleted, and `minCount` guarantees a floor. A `Backup` joins a policy through one label; that label is stamped from a `retentionPolicyName` field shared by `Plan`, `BackupJob`, and `BackupClass`, the last acting as the namespace default. Enumeration and pruning of `Backup` objects live in a core controller, and physical reclamation of the object-store artifact is delegated to the strategy driver, exactly as the Velero path already turns a `Backup` deletion into a `DeleteBackupRequest`. This closes [cozystack/cozystack#3965](https://github.com/cozystack/cozystack/issues/3965).
1313

1414
## Scope and related proposals
1515

@@ -47,7 +47,7 @@ A tenant running an hourly `Plan` against Postgres has no way to say "keep the l
4747
- A declarative, strategy-agnostic retention control covering age (`maxAge`), a count ceiling (`maxCount`), and a count floor (`minCount`), usable independently or in combination.
4848
- Cleanup for strategies whose operators have no native retention (ClickHouse, MongoDB, etcd, FoundationDB), by having core enumerate and prune `Backup` objects and delegating physical deletion to the driver.
4949
- One policy attachable to both scheduled (`Plan`) and ad-hoc (`BackupJob`) backups, with a platform default carried on `BackupClass`.
50-
- The platform, not the application operator, owns the artifact lifecycle end to end.
50+
- The user's declared policy, not an operator's hidden native TTL, decides when an artifact is removed; retention is opt-in and nothing is deleted without a policy the tenant authored.
5151
- Migration of existing artifacts between policies without recreating them.
5252

5353
### Non-goals
@@ -96,7 +96,7 @@ Both `Backup` and `BackupRetentionPolicy` are namespaced, and matching is scoped
9696

9797
### Platform-owned cleanup contract
9898

99-
The platform is the single authority that decides when a `Backup` is removed; it does not delegate expiry to an application operator's TTL or retention window. Deletion is driven through the `Backup` object, and the strategy driver reclaims both the record and the physical archive on the platform's behalf. Every driver that reclaims physically MUST honor:
99+
The user's `BackupRetentionPolicy` is the single source of truth for when a `Backup` is removed, enforced by one mechanism — the core sweep — rather than split between that policy and an application operator's hidden native TTL. Nothing is deleted that the tenant's policy did not ask for, and a `Backup` under no policy is never swept. Deletion is driven through the `Backup` object, and the strategy driver reclaims both the record and the physical archive. Every driver that reclaims physically MUST honor:
100100

101101
1. **Single authority.** The operator's native retention (CNPG `Cluster.spec.backup.retentionPolicy`, MariaDB `maxRetention`) is unset, so the operator and the core sweep never race over the same archive.
102102
2. **Idempotency and finalizer-hold.** The `backups.cozystack.io/cleanup` finalizer holds the `Backup` until the driver confirms the archive is gone; a retried or duplicated deletion is a no-op.
@@ -177,7 +177,7 @@ kubectl label backup -n tenant-acme \
177177

178178
## Upgrade and rollback compatibility
179179

180-
`retentionPolicyName` is optional on all three types, so existing clusters and manifests keep working; a `Backup` with no label is never swept, matching today's "never cleaned" behavior. Adopting platform-owned cleanup for a driver that had native retention (CNPG, MariaDB) requires unsetting that native retention as part of the same change, so the two authorities never overlap. Rollback is removing the policy objects and the field; already-deleted artifacts are not recoverable, so that direction is one-way, but no data is deleted merely by reverting the controller.
180+
`retentionPolicyName` is optional on all three types, so existing clusters and manifests keep working; a `Backup` with no label is never swept, matching today's "never cleaned" behavior. Adopting policy-driven cleanup for a driver that had native retention (CNPG, MariaDB) requires unsetting that native retention as part of the same change, so the two mechanisms never overlap. Rollback is removing the policy objects and the field; already-deleted artifacts are not recoverable, so that direction is one-way, but no data is deleted merely by reverting the controller.
181181

182182
## Security
183183

0 commit comments

Comments
 (0)