Skip to content

docs: document version error detection and handling (webhook rejections + ExtensionRollback event) #433

Description

@xgerman

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/:

  1. 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...

  2. Webhook rejection when schemaVersion exceeds binary:

    schemaVersion X exceeds the binary version Y; schema version must be <= binary version

  3. 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

  • Troubleshooting section documents the two webhook rejections + the ExtensionRollback event.
  • Each includes detection steps (apply failure / kubectl get events / describe) and a concrete recovery action.

Metadata

Metadata

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

Status
Backlog

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions