Skip to content

docs: document version compatibility for backup/restore (restore into >= backup schema version) #434

Description

@xgerman

Summary

There is no guidance on version compatibility during backup/restore. Restoring a backup onto a mismatched (older) engine binary is unsafe and — importantly — is not caught by admission validation on a fresh restore.

Investigation findings

  • Backups carry no version metadata. BackupStatus (operator/src/api/preview/backup_types.go) records only phase/timestamps/message — no schema version, no engine image. There is no way to read the schema version off a Backup CR.
  • Restore is a physical CNPG recovery (object-store backup / volume snapshot / PV; see getBootstrapConfiguration in operator/src/internal/cnpg/cnpg_cluster.go). The database catalog — including the installed documentdb extension schema — is restored as-is, so restored data is at whatever schema version existed at backup time.
  • The restored cluster's binary version is set independently by the new DocumentDB spec's documentDBVersion/image — there is no link to the backup.
  • The rollback webhook guard does NOT protect restores. validateImageRollback compares against oldDB.Status.SchemaVersion; on a fresh restore this is a brand-new resource with an empty status, so the guard is a no-op. This means you can restore a schema-0.110 backup onto an older 0.109 binary with no protection — the exact "old binary vs. newer schema" data-corruption scenario the guard exists to prevent.

Documentation guidance to add

  • Restore into a binary version >= the schema version the backup was taken with (ideally the same documentDBVersion it was backed up with). Restoring onto an older binary is unsafe and is not caught by admission validation on a fresh restore.
  • How to detect the schema version of a backup (since it isn't stored):
    • Record the source cluster's status.schemaVersion before taking the backup (recommended operational practice).
    • Otherwise, restore into a cluster whose binary is >= the expected version, then read kubectl get documentdb <name> -o jsonpath='{.status.schemaVersion}' (derived from pg_available_extensions).

Follow-up (engineering, out of scope for docs)

Consider capturing schema version in BackupStatus at backup time, and/or extending restore validation to guard binary-vs-restored-schema. Tracked separately if we decide to pursue.

Acceptance criteria

  • Backup/restore docs state the "restore into a version >= backup schema version" rule and call out that restores are not protected by admission validation.
  • Backup/restore docs explain how to determine/record a backup's schema version.

Metadata

Metadata

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions