Activate `spec.documentDBVersion` field

[WentingWu666666]

Summary

Enable users to specify which DocumentDB extension version to deploy via spec.documentDBVersion, add version validation and upgrade path enforcement, and expand the upgrade CI workflow to test version transitions using spec.documentDBVersion.

Details

Background:
The spec.documentDBVersion field and DOCUMENTDB_VERSION environment variable are implemented but not actively validated or enforced. This issue combines version management activation with comprehensive upgrade testing.

Blocked By: Gateway images with version tags are currently broken: The documentdb-local:pg16-0.1XX.0 images in the documentdb repository were built for standalone mode (where PostgreSQL runs inside the same container with Unix socket), not for CNPG sidecar mode (where PostgreSQL runs in a separate container with TCP only). These images cannot be used with the Kubernetes operator's CNPG-based architecture.

Impact: We only have one working documentdb-local image (:16 tag), so we cannot:

• Set documentDBVersion for gateway deployments
• Test gateway image upgrades between versions

Once versioned gateway images are rebuilt for CNPG sidecar mode, we can enable full version management.

Current State:

• spec.documentDBVersion field exists in DocumentDB CRD
• status.documentDBVersion tracks the current running version
• DOCUMENTDB_VERSION env var is set on gateway container
• Version extraction from image tag implemented in util.go
• Basic upgrade workflow tests extension images only (0.109.0 → 0.110.0)
• Gateway image upgrade testing is blocked (only one working image)

What's Missing:

Version Management:

1. Version format validation (ensure valid semver like 0.110.0)
2. Version compatibility matrix documentation
3. Upgrade path validation (prevent downgrades without explicit flag)
4. Gateway version support (blocked on image fixes)

CI Testing:

1. Use spec.documentDBVersion in upgrade workflow tests
2. Version matrix for multiple upgrade paths
3. Gateway image upgrade testing (blocked on image fixes)
4. Downgrade prevention testing

Implementation Steps:

1. Add version validation in controller:

   func validateDocumentDBVersion(version string) error {
       // Validate version format matches X.Y.Z pattern
       // Return error for invalid formats
   }

2. Add upgrade path validation:

   func canUpgrade(currentVersion, targetVersion string) bool {
       // Parse semver versions
       // Ensure targetVersion >= currentVersion
       // Allow downgrade only with explicit annotation
   }

3. Add condition to DocumentDB status for version validation errors

4. Update public documentation with supported versions

5. Update upgrade CI workflow to use spec.documentDBVersion:

   jobs:
     test-upgrade:
       strategy:
         matrix:
           upgrade:
             - from_version: "0.109.0"
               to_version: "0.110.0"
             - from_version: "0.110.0"
               to_version: "0.111.0"
           architecture: [amd64, arm64]
       steps:
         - name: Deploy with spec.documentDBVersion = ${{ matrix.upgrade.from_version }}
         - name: Update spec.documentDBVersion to ${{ matrix.upgrade.to_version }}
         - name: Verify data persistence
         - name: Rollback spec.documentDBVersion to ${{ matrix.upgrade.from_version }}

Example Usage:

apiVersion: documentdb.io/preview
kind: DocumentDB
metadata:
  name: my-cluster
spec:
  documentDBVersion: "0.110.0"  # Pin to specific version

Test Scenarios:

Currently Possible (extension images work):

1. Extension upgrade via spec.documentDBVersion change
2. Extension rollback via spec.documentDBVersion change
3. Downgrade prevention testing

Blocked (waiting for versioned gateway images):
4. Gateway-only upgrade (extension stays same version)
5. Both extension + gateway upgrade simultaneously
6. Skip-version upgrade (e.g., 0.109.0 → 0.111.0)

Acceptance Criteria:

Phase 1 (extension only):

• Users can specify spec.documentDBVersion: "0.110.0"
• Controller validates version format and rejects invalid versions
• status.documentDBVersion accurately reflects running version
• Upgrade workflow tests use spec.documentDBVersion in DocumentDB spec
• Extension upgrade from 0.109.0 → 0.110.0 works via spec change
• Downgrade is blocked (or requires explicit annotation)

Phase 2 (after gateway images fixed):

• Gateway version management enabled
• Gateway upgrade tested separately from extension
• Workflow uses full version matrix for both extension and gateway