Summary
Our version handling (schema version, extension/gateway image) is now surfaced in DocumentDB.status, and the upgrade flow enforces version-safety rules. However, the documentation does not explain how to detect and handle version error conditions, and there is no guidance on version compatibility during backup/restore. This issue tracks the documentation work.
Part 1 — Document detecting/handling version error conditions
The code produces version-related error signals that are not documented anywhere under docs/operator-public-documentation/preview/:
- Webhook rejection on image rollback (
operator/src/internal/webhook/documentdb_webhook.go): setting documentDBVersion/image below the installed schema fails kubectl apply synchronously with:
image rollback blocked: requested version X is older than installed schema version Y. ALTER EXTENSION has no downgrade path...
- Webhook rejection when
schemaVersion exceeds binary:
schemaVersion X exceeds the binary version Y; schema version must be <= binary version
ExtensionRollback warning Event emitted by the controller (documentdb_controller.go) as a defense-in-depth guard — detectable via kubectl describe documentdb / kubectl get events.
The operations/upgrades.md "Rollback and Recovery" section explains the rules ("the operator rejects it") but never shows the actual error text or tells users how to detect these conditions (events / describe / apply failure) and what to do for each.
Ask: Add a "Troubleshooting version errors" section (in upgrades.md or a new page) covering, for each signal above: how to detect it, the exact message, and the recovery action.
Part 2 — Document version compatibility for backup/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). 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 the restore validation to guard binary-vs-restored-schema. Tracked separately if we decide to pursue.
Acceptance criteria
Summary
Our version handling (schema version, extension/gateway image) is now surfaced in
DocumentDB.status, and the upgrade flow enforces version-safety rules. However, the documentation does not explain how to detect and handle version error conditions, and there is no guidance on version compatibility during backup/restore. This issue tracks the documentation work.Part 1 — Document detecting/handling version error conditions
The code produces version-related error signals that are not documented anywhere under
docs/operator-public-documentation/preview/:operator/src/internal/webhook/documentdb_webhook.go): settingdocumentDBVersion/image below the installed schema failskubectl applysynchronously with:schemaVersionexceeds binary:ExtensionRollbackwarning Event emitted by the controller (documentdb_controller.go) as a defense-in-depth guard — detectable viakubectl describe documentdb/kubectl get events.The
operations/upgrades.md"Rollback and Recovery" section explains the rules ("the operator rejects it") but never shows the actual error text or tells users how to detect these conditions (events / describe / apply failure) and what to do for each.Ask: Add a "Troubleshooting version errors" section (in
upgrades.mdor a new page) covering, for each signal above: how to detect it, the exact message, and the recovery action.Part 2 — Document version compatibility for backup/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.documentdbextension 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 the restore validation to guard binary-vs-restored-schema. Tracked separately if we decide to pursue.Acceptance criteria
ExtensionRollbackevent with detection steps and recovery actions.