Rollback: Safeguards and recovery

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.yaml are 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.