Summary
Version handling is surfaced in DocumentDB.status (schemaVersion, documentDBImage, gatewayImage) and the upgrade flow enforces version-safety rules, but the documentation does not explain how to detect and handle version error conditions.
Undocumented error signals
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 (operator/src/internal/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.
Acceptance criteria
Summary
Version handling is surfaced in
DocumentDB.status(schemaVersion,documentDBImage,gatewayImage) and the upgrade flow enforces version-safety rules, but the documentation does not explain how to detect and handle version error conditions.Undocumented error signals
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 (operator/src/internal/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.Acceptance criteria
ExtensionRollbackevent.kubectl get events/describe) and a concrete recovery action.