Allows rollback only to a version that already passed health gates, requires a schema-compat check, and prefers roll-forward when irreversible data migration has already landed.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Rollback of a production deploy may target only a version that previously passed the same health gates now in force. Before traffic moves, a schema-compat check must show the data plane still works with that version. When a forward migration has already rewritten data in a way the prior version cannot read, operators roll forward to a patched version instead of pinning the old binary.
Scope
- Version pin selection, health-gate reuse, schema-compat evidence, roll-forward preference, dual-control for ungated pins, and post-rollback soak for production deploys of backend services.
- Interaction with readiness and liveness probes as gate inputs, not as the only gate.
- Recording of why rollback was chosen versus abort-in-place.
Outside this block
- Automatic canary abort while the new version still has a declared slice.
- One-click restore of databases from backup snapshots.
Contract
- The rollback target identifier must appear in the gate ledger as passed for production; unknown or failed versions cannot be pinned.
- Schema-compat fails if the current data revision is newer than the target's declared compatible range.
- When schema-compat fails, the runbook selects roll-forward: ship a hotfix version through the normal gates rather than forcing the old binary.
- Health gates include error rate, probe failures, and dependency readiness from the same SLIs used at original promote.
- A rollback that skips gates requires two operators and a tracked incident identifier.
- After pin, a soak window must complete without gate breach before the incident is marked mitigated.
Implementation guidance
- Store every production promote with version, gate results, and compatible schema range.
- Make rollback a pipeline job that reads the ledger; ad-hoc kubectl set image to an unlisted tag is a policy violation.
Failure handling
- Ledger unavailable: rollback job fails closed; it does not pick the previous replica-set spec blindly.
- Mixed replicas after a partial pin are an incident: finish the pin or return to the last fully gated set.
Verification and operations
- Measure rollbacks to ungated versions (should be zero), schema-compat blocks, roll-forward vs pin, and soak failures after pin.
- Alert when live replicas run a version absent from the gate ledger.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.
References
- Health-gate reuse, schema-compat ranges, and roll-forward preference are project decisions recorded in this package; they are not a public standard.