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:
parent
f5c97d1f36
commit
f3f80443d0
1 changed files with 44 additions and 0 deletions
44
docs/backup/service-backup-template.md
Normal file
44
docs/backup/service-backup-template.md
Normal 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>
|
||||||
Loading…
Add table
Reference in a new issue