feat: adopt the shared expand-migrate-contract upgrade flow for glance

[berendt]

Summary

Glance's release upgrades ran a single glance-manage db sync before the workload rolled — and db sync executes expand → migrate → contract in one pass, so the destructive contract half ran while previous-release pods were still serving. Keystone already solved this with a four-phase upgrade machine (Expanding → Migrating → RollingUpdate → Contracting) that was keystone-private. This branch extracts that machine into internal/common/database, rewires Keystone onto it with frozen behavior, and adopts it for Glance as the second consumer, then corrects the onboarding skill and docs so the next database-backed service decides this at onboarding time.

Closes #734

Change set (commit order)

The eight commits are ordered so each is independently compiling — the shared flow lands first while keystone's private machine still works, then keystone is cut over, then glance adopts it, then tests and docs.

1. 7f0dd9d4 refactor: move the UpgradePhase type into the shared commonv1 package
   Moves UpgradePhase and its four constants (Expanding/Migrating/RollingUpdate/Contracting) from keystone_types.go into internal/common/types/types.go, so the shared flow can reference them. Keystone keeps a type UpgradePhase = commonv1.UpgradePhase alias plus a re-exported constant block (the GatewaySpec alias pattern), so every existing reference compiles unchanged. The generated CRD is byte-identical — the enum marker travels with the type and the schema description comes from the status-field godoc.

2. a6f37258 feat: add the shared expand-migrate-contract upgrade flow
   Ports keystone's private four-phase machine into internal/common/database/upgrade.go, parameterized over a single seam — the spec-side release string — via UpgradeFlowParams (owner CR, condition vocabulary, SpecRelease, BuildPhaseJob closure, terminal-metric callback). Exports IsUpgrade, InitiateUpgrade, ReconcileUpgrade, AbortUpgrade, and CompleteRollingUpdate with keystone's exact condition/event reasons and message wording. Two service-specific phrasings are neutralized ("Image tag changed" → "Spec release changed"). Keystone's private machine stays in place and compiling — a later commit deletes it. Ships with the shared unit suite (upgrade_test.go, +538) covering phase transitions, abort, target-changed, unknown phase, and the parse/downgrade/sequential rejections.

3. d0ac12d0 refactor: rewire keystone onto the shared database upgrade flow
   Deletes reconcile_upgrade.go (−316) and routes reconcileDatabase/reconcileDeployment through InitiateUpgrade/ReconcileUpgrade/AbortUpgrade/CompleteRollingUpdate. buildExpandJob/buildMigrateJob/buildContractJob become the BuildPhaseJob closure. Behavior is frozen — reasons, events, db_sync metric suffixes, and the abort semantics are unchanged; the keystone unit/envtest/e2e suites pass with no test edits. Two seams stay keystone-local deliberately (documented in the commit): the target-changed guard keeps its "image tag changed" prose that a unit test pins, and only the reason constants keystone still emits or tests reference by name are aliased (aliasing the rest would leave unused constants the linter rejects).

4. a623a085 feat: add status.upgradePhase to the Glance CRD
   Adds UpgradePhase commonv1.UpgradePhase to GlanceStatus and regenerates the two Glance CRD copies (config/crd/bases + the Helm chart). Reuses the shared type, so the Glance CRD gains the same four-value enum keystone already carries; no other operator's CRD or deepcopy output changes.

5. a64a8be4 feat: adopt the shared upgrade flow for glance release transitions
   Glance becomes the second consumer. A release transition (non-patch step, e.g. 2025.2 → 2026.1) now walks the four phases with glance-manage db expand|migrate|contract phase Jobs, driven identically to keystone; status.upgradePhase tracks the active phase and TargetRelease is owned by the flow. Fresh installs and patch bumps stay on the single-pass db sync path. Documented behavior change in failure reporting only: the bespoke InvalidReleaseTransition reason and its non-zero-requeue short-circuit are gone — an invalid transition now surfaces through the shared vocabulary (VersionParseError, DowngradeNotSupported, UpgradePathInvalid) as a returned error, so the controller backs off with exponential retry exactly like keystone. The accepted set of transitions is unchanged (patch-only or a single sequential step, no downgrade). Deployment reconcile flips RollingUpdate → Contracting once the rollout is ready, and the eventlet → uWSGI launch-mode switch derives from spec.openStackRelease.

6. e41bec21 test: cover the glance upgrade phase walk in envtest
   Adds a glance integration test driving a full 2025.2 → 2026.1 upgrade against envtest (which runs no Job/Deployment controllers, so completions are simulated), mirroring keystone's upgrade-cycle test. Locks four properties together: the Expanding → Migrating → RollingUpdate → Contracting walk with each phase Job carrying the target image; the rollout-gated contract flip (stays RollingUpdate until the re-imaged Deployment reports ready, asserted with a Consistently); the eventlet → uWSGI launch-command switch; and the post-upgrade steady-state db-sync re-run on pod-spec-hash drift.

7. e4012b03 test: add the glance release-upgrade e2e suite
   Adds tests/e2e/glance/release-upgrade/ — the cross-release upgrade end-to-end, making glance the second consumer exercised by a chainsaw suite. Deploys at 2025.2 with a default S3 backend (glance cannot go Ready without one), asserts the pre-upgrade steady state, patches spec.openStackRelease + spec.image.tag to 2026.1, then asserts the drain: Ready/AllReady, installedRelease promoted to 2026.1, upgradePhase cleared, the three phase Jobs left in place, the Deployment flipped to the uWSGI command on the :2026.1 image, and the steady-state db-sync re-run (its db load_metadefs loads the 2026.1 definitions). Auto-discovered by the per-operator chainsaw run — no CI wiring changes.

8. aec287bd docs: document the glance upgrade flow and fix the onboarding skill
   Adds docs/reference/glance/glance-upgrade-flow.md mirroring the keystone page (phase table with exact commands/Job names, the launch-mode flip, condition reasons/events, abort semantics, the image/release lockstep contract with its digest-pinning nuance, the post-upgrade metadefs reload). Updates the glance CRD/reconciler/events/index pages (drops the "no upgradePhase field" and every InvalidReleaseTransition claim, adds the new rows/reasons/events, links the page from the sidebar). Adds a shared-machinery note to the keystone upgrade-flow page. In prepare-new-service, extends the database profiling bullet to ask which zero-downtime upgrade mechanism the manage tool supports and to adopt the shared database.ReconcileUpgrade flow, and drops expand-migrate-contract from the keystone-specific category-3 list now that it is shared category-1 machinery.

Divergences from the issue

• The issue lists operators/glance/internal/controller/db_job_metrics.go and keystone's reconcile_database_test.go / integration_test.go as touch points, but they do not appear in the diff. This is consistent with the commits: glance's DB-Job metrics were already suffix-generic (so db-expand/db-migrate/db-contract flow through recordDBJobTerminalState unchanged), and the keystone rewire was behavior-preserving enough that its existing upgrade assertions needed no edits — the acceptance criteria explicitly require those keystone suites to pass without modification. The one new keystone test file in the diff is reconcile_deployment_test.go (+55), covering the CompleteRollingUpdate cutover.

Verification

Acceptance criteria are covered by the shared-flow unit suite (internal/common/database/upgrade_test.go), the glance unit/envtest additions, and the new glance release-upgrade e2e suite. Full CI (keystone + glance unit, envtest, and the upgrade e2e suites) runs on this PR.

---

Implemented by planwerk-agent 494b8a9 with Claude:claude-opus-4-8

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}