extern/zrepl
1
0
Fork 0
mirror of https://github.com/zrepl/zrepl.git synced 2024-11-22 00:13:52 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: adjust prune to rst

Browse Source
This commit is contained in:
Christian Schwarz 2017-11-10 13:28:05 +01:00
parent 0a77be0ff2
commit 69084fb08f
2 changed files with 25 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/configuration/jobs.rst
View File

@ -7,6 +7,8 @@
.. |filter| replace:: :ref:`filter <pattern-filter>` .. |filter| replace:: :ref:`filter <pattern-filter>`
.. |prune| replace:: :ref:`prune <prune>` .. |prune| replace:: :ref:`prune <prune>`
.. _job:
Job Types Job Types
========= =========

43
docs/configuration/prune.rst
View File

@ -1,16 +1,18 @@
.. _prune: .. _prune:
Snapshot Pruning Pruning Policies
================ ================
In zrepl, *pruning* means *destroying snapshots by some policy*. 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. 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. 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. Check the respective :ref:`job definition <job>` for details.
Currently, the retention grid is the only supported pruning policy. Currently, the :ref:`prune-retention-grid` is the only supported pruning policy.
.. _prune-retention-grid:
Retention Grid Retention Grid
-------------- --------------
@ -29,33 +31,34 @@ Retention Grid
└─ 24 adjacent one-hour intervals └─ 24 adjacent one-hour intervals
The retention grid can be thought of as a time-based sieve: The retention grid can be thought of as a time-based sieve:
The ``grid`` field specifies a list of adjacent time intervals:
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.
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. All intervals to its right describe time intervals further in the past.
Each interval carries a maximum number of snapshots to keep. 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. 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 default value is **1**.
The following procedure happens during pruning: The following procedure happens during pruning:
1. The list of snapshots eligible for pruning is sorted by `creation` #. 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 #. 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 #. A list of buckets is created, one for each interval
1. The list of snapshots is split up into the buckets. #. The list of snapshots is split up into the buckets.
1. For each bucket #. For each bucket
1. the contained snapshot list is sorted by creation. #. the contained snapshot list is sorted by creation.
1. snapshots from the list, oldest first, are destroyed until the specified `keep` count is reached. #. snapshots from the list, oldest first, are destroyed until the specified ``keep`` count is reached.
1. all remaining snapshots on the list are kept. #. all remaining snapshots on the list are kept.
.. ATTENTION:: .. ATTENTION::
The configuration of the first interval (`1x1h(keep=all)` in the example) determines the **maximum allowable replication lag** between source and destination. .. TODO this is obsolete as soon as bookmarks are created during snapshotting
The configuration of the first interval (``1x1h(keep=all)`` in the example) determines the **maximum allowable replication lag** between source and destination.
After the first interval, source and destination likely have different retention settings. After the first interval, source and destination likely have different retention settings.
This means source and destination may prune different snapshots, prohibiting incremental replication froms snapshots that are not in the first interval. This means source and destination may prune different snapshots, prohibiting incremental replication froms snapshots that are not in the first interval.
**Always** configure the first interval to **`1x?(keep=all)`**, substituting `?` with the maximum time replication may fail due to downtimes, maintenance, connectivity issues, etc. **Always** configure the first interval to ``1x?(keep=all)``, substituting ``?`` with the maximum time replication may fail due to downtimes, maintenance, connectivity issues, etc.
After outages longer than `?` you may be required to perform **full replication** again. After outages longer than ``?`` you may be required to perform **full replication** again.