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