diff --git a/docs/operations/backup-and-restore.md b/docs/operations/backup-and-restore.md index b319155..6db3026 100644 --- a/docs/operations/backup-and-restore.md +++ b/docs/operations/backup-and-restore.md @@ -9,6 +9,9 @@ MongoDB database behind a Vantage control plane. It talks to MongoDB directly, never to the Vantage API, so it works against a control plane that is down, half-migrated, or gone — exactly the situation a backup tool has to survive. +For the store-level overview — what holds what, and why the database alone is +not a backup — see [Backups](./backups.md). This page covers the tool. + :::danger The key comes first Vantage encrypts SSH private keys, key passphrases, vault secrets, SSO client secrets and console credentials with `KEY_ENCRYPTION_KEY`. **It is not in your diff --git a/docs/operations/backups.md b/docs/operations/backups.md index 481966a..897bfa5 100644 --- a/docs/operations/backups.md +++ b/docs/operations/backups.md @@ -24,7 +24,23 @@ values is permanently unreadable. Store the key somewhere other than the server it protects. ::: -## Backing up MongoDB +:::info Use `vantagectl` +[**Backup and restore**](./backup-and-restore.md) is the supported way to take +and restore a backup. It writes an archive that carries a fingerprint of +`KEY_ENCRYPTION_KEY` — never the key — so a restore taken with the wrong key +**refuses** rather than silently producing a database whose secrets nobody can +read. It also checksums every archive member before writing anything, and +refuses to restore into a database that already holds data. A plain +`mongodump` does none of that: it records nothing about which key the data was +encrypted under, so a restore from one succeeds even when the key is wrong and +the failure only shows up later, as unreadable secrets. + +The rest of this page, past the table above, describes the `mongodump` / +`mongorestore` fallback for an operator who does not have `vantagectl` +available. Prefer the linked page. +::: + +## Backing up MongoDB (fallback, without `vantagectl`) With the bundled Mongo container: @@ -33,6 +49,13 @@ docker compose exec -T mongo mongodump --archive --gzip --db vantage \ > /backups/vantage-$(date +%F).archive.gz ``` +:::warning +This archive records nothing about which `KEY_ENCRYPTION_KEY` it was taken +under. Restoring it with the wrong key produces a database that looks intact +and is not — every secret in it is silently unreadable until something tries +to decrypt one. +::: + Restoring: ```bash @@ -69,12 +92,13 @@ What it does **not** do is reconcile the world. After a restore: | What | When | | ----------------- | ----------------------------------------------------- | -| MongoDB dump | Nightly, retained per your policy | +| Backup | Nightly, retained per your policy | | Environment file | On change, held in a password manager or secret store | | Restore rehearsal | Occasionally, into a throwaway host | Rehearse a restore now and again. It is the step most often skipped, and the one -that finds the problems. +that finds the problems. See [Backup and restore](./backup-and-restore.md) for +the drill, and for `verify`, which checks a backup is real without a restore. ## Cloud instances