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
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
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 aBackupCR.getBootstrapConfigurationinoperator/src/internal/cnpg/cnpg_cluster.go). The database catalog — including the installeddocumentdbextension schema — is restored as-is, so restored data is at whatever schema version existed at backup time.DocumentDBspec'sdocumentDBVersion/image — there is no link to the backup.validateImageRollbackcompares againstoldDB.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.110backup onto an older0.109binary with no protection — the exact "old binary vs. newer schema" data-corruption scenario the guard exists to prevent.Documentation guidance to add
documentDBVersionit was backed up with). Restoring onto an older binary is unsafe and is not caught by admission validation on a fresh restore.status.schemaVersionbefore taking the backup (recommended operational practice).kubectl get documentdb <name> -o jsonpath='{.status.schemaVersion}'(derived frompg_available_extensions).Follow-up (engineering, out of scope for docs)
Consider capturing schema version in
BackupStatusat backup time, and/or extending restore validation to guard binary-vs-restored-schema. Tracked separately if we decide to pursue.Acceptance criteria