Rollback Deploy Auto

Automatically roll back a deployment to the last known good version with zero-downtime switching.

When to Use This Command

Run this command when you need to:

• Revert a production deployment that introduced regressions or errors
• Execute an automated rollback with traffic management and health validation
• Restore service to a specific previous version with database compatibility checks

Consider alternatives when:

• The issue can be resolved with a quick forward fix that is less risky than a rollback
• Database migrations in the new version make rollback destructive to data

Quick Start

Configuration

Copy
name: rollback-deploy-auto
type: command
category: deployment

Example Invocation

Copy
claude command:run rollback-deploy-auto --version v2.14.3 --strategy rolling

Example Output

Rollback Target: v2.14.3
Current Version: v2.14.4
Strategy: rolling

Pre-rollback checks:
  [OK] Target version v2.14.3 image exists in registry
  [OK] No destructive database migrations between versions
  [OK] Configuration compatible with target version
  [OK] Database backup completed: backup-20260315-103200.sql

Executing rollback:
  [1/4] Draining traffic from current pods...done
  [2/4] Deploying v2.14.3 (pod 1/3)...healthy
  [3/4] Deploying v2.14.3 (pod 2/3)...healthy
  [4/4] Deploying v2.14.3 (pod 3/3)...healthy

Post-rollback validation:
  [OK] Health endpoint: 200 OK
  [OK] Error rate: 0.01% (within baseline)
  [OK] p95 latency: 145ms (within baseline)

Rollback to v2.14.3 completed in 2m 34s.
All pods healthy. Traffic fully restored.

Core Concepts

Rollback Strategy Overview

Aspect	Details
Rolling Rollback	Replace pods one at a time with health gates between each
Blue-Green Switch	Redirect traffic from green (new) back to blue (old) instantly
Canary Reversal	Remove canary pods and restore 100% traffic to stable version
Database Safety	Check for irreversible migrations before allowing rollback
Data Backup	Automatic database snapshot before any rollback operation

Rollback Execution Workflow

  Rollback Triggered
        |
        v
  +-------------------+
  | Version Lookup    |---> Verify target image exists
  +-------------------+
        |
        v
  +-------------------+
  | Migration Check   |---> Any destructive DDL?
  +-------------------+
        |
        v
  +-------------------+
  | Database Backup   |---> Snapshot current state
  +-------------------+
        |
        v
  +-------------------+
  | Traffic Drain     |---> Graceful connection drain
  +-------------------+
        |
        v
  +-------------------+
  | Deploy Old Version|---> Rolling / Blue-Green / Instant
  +-------------------+
        |
        v
  +-------------------+
  | Health Validation  |---> Probes + metric checks
  +-------------------+

Configuration

Parameter	Type	Default	Description
version	string	previous	Target version tag to roll back to
strategy	string	rolling	Rollback strategy: rolling, blue-green, or instant
backup	boolean	true	Create database backup before rollback
timeout	integer	300	Maximum seconds to wait for rollback to complete
dry_run	boolean	false	Simulate rollback without applying changes

Best Practices

1. Always Check Migration Compatibility - Before rolling back, verify that no irreversible database schema changes were applied. Dropping columns or tables in the new version makes rollback impossible without data restoration.

2. Back Up Before Rolling Back - Take a database snapshot even if you believe the rollback is safe. The backup takes minutes but can save hours of data recovery if something goes wrong during the process.

3. Use Rolling Strategy by Default - Rolling rollbacks maintain availability throughout the process. Reserve instant rollbacks for catastrophic failures where any delay in restoring service is unacceptable.

4. Monitor for 30 Minutes After Rollback - A successful rollback is not confirmed until metrics stabilize. Watch error rates, latency, and user-reported issues for at least 30 minutes before declaring the incident resolved.

5. Record the Rollback Decision - Document why the rollback was necessary, what version was restored, and what the plan is for a forward fix. This creates accountability and prevents the same issue from shipping again.

Common Issues

1. Target Image Not Found in Registry - The container image for the rollback version was garbage-collected. Configure your registry to retain at least the last 5 production release images to ensure rollback targets are always available.

2. Rollback Blocked by Migration Check - A schema migration between versions prevents safe rollback. In this case, apply a forward fix or manually reverse the migration with a new migration file before retrying the rollback.

3. Health Checks Fail After Rollback - The old version expects configuration or environment variables that were changed in the new version. Restore the configuration snapshot that matches the target version, not just the application code.