diff --git a/docs/content/configuration/prune.md b/docs/content/configuration/prune.md index 97ebc57..9be96da 100644 --- a/docs/content/configuration/prune.md +++ b/docs/content/configuration/prune.md @@ -1,9 +1,50 @@ +++ -title = "Pruning" +title = "Pruning Policies" description = "Automated pruning of snapshots" weight = 40 +++ -{{% alert theme="warning" %}}Under Construction{{% /alert %}} +In zrepl, *pruning* means *destroying snapshots by some policy*. + +A *pruning policy* takes a list of snapshots and - for each snapshot - decides whether it should be kept or destroyed. + +The job context defines which snapshots are even considered for pruning, for example through the `snapshot_prefix` variable. +Check the [job definition]({{< relref "configuration/jobs.md">}}) for details. + +Currently, the retention grid is the only supported pruning policy. ## Retention Grid + +```yaml +jobs: +- name: pull_app-srv + ... + prune: + policy: grid + grid: 1x1h(keep=all) | 24x1h | 35x1d | 6x30d + │ │ + └─ one hour interval + │ + └─ 24 adjacent one-hour intervals +``` + +The retention grid can be thought of as a time-based sieve: + +The `grid` field specifies a list of adjacent time intervals: +the left edge of the leftmost (first) interval is the `creation` date of the youngest snapshot. +All intervals to its right describe time intervals further in the past. + +Each interval carries a maximum number of snapshots to keep. +It is secified via `(keep=N)`, where `N` is either `all` (all snapshots are kept) or a positive integer. +The default value is **1**. + +The following procedure happens during pruning: + +1. The list of snapshots eligible for pruning is sorted by `creation` +1. The left edge of the first interval is aligned to the `creation` date of the youngest snapshot +1. A list of buckets is created, one for each interval +1. The list of snapshots is split up into the buckets. +1. For each bucket + 1. the contained snapshot list is sorted by creation. + 1. snapshots from the list, oldest first, are destroyed until the specified `keep` count is reached. + 1. all remaining snapshots on the list are kept.