docs(backup): add BACKUP.md template + backup__* contract (ADR-022)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
sjat 2026-06-10 11:20:01 +02:00
parent f5c97d1f36
commit f3f80443d0

View file

@ -0,0 +1,44 @@
# Per-service backup record — template
Copy this file to `roles/<service>/BACKUP.md` when building a **stateful** service
role (ADR-022). It is the per-service **backup record**: what state the service holds,
how it is captured consistently, and how it is restored. The structured parts are
**rendered from the role's `backup__*` data** (the single source of truth that also
drives `/check-backup`) — keep the data authoritative and regenerate this file rather
than hand-editing the tables. The prose "Restore notes" tail is hand-written.
A **stateless** service (holds no persistent data) does not get a `BACKUP.md`; it sets
`backup__state: false` with a reason in its role defaults instead.
Delete this preamble in the copy and start from the heading below.
---
# Backup — <service>
## State captured
Rendered from `backup__*`:
| What | Source | How captured |
|---|---|---|
| data dir(s) | `<backup__paths[*]>` | file-level, pulled read-only |
| database | `<backup__dumps[*].cmd>``<backup__dumps[*].dest>` | logical dump (default; ADR-022 Decision 7) |
- **Quiesce:** `<backup__quiesce>``true` means the service is stopped → backed up →
restarted (escape hatch for data that cannot be dumped live; ADR-022 Decision 7 B).
- **RPO:** ~24 h (nightly; ADR-022 Decision 2).
## Restore procedure
1. Re-provision the host (Terraform) and redeploy this role (Ansible) — Model A.
2. `restic restore` the latest snapshot for `<backup__service>` into `<backup__paths>`.
3. Replay each `<backup__dumps[*].dest>` into its database.
4. Confirm with this role's `VERIFY.md` checks (ADR-008/017).
## Restore notes
Prose the data can't capture — ordering gotchas, "restore the DB before the data dir",
known-tricky migrations.
- <none yet>