AWS CodeDeploy Rollback Explained: EC2 vs ECS vs Lambda

Simple explanation

CodeDeploy rollback is a version-control undo for your running application. When you deploy a new version and something breaks, CodeDeploy can automatically switch back to the last version that worked.

The key insight is that “reverting” means something different on each platform:

• EC2: The old code gets re-installed on your servers. It takes a few minutes because the installation steps run again.
• ECS: Traffic is flipped back to the old containers, which were never shut down. It takes seconds.
• Lambda: A pointer (the alias) is updated to point back to the old function version. It is near-instant.

If you are new to CodeDeploy, read the AWS CodeDeploy Overview first to understand applications, deployment groups, and lifecycle hooks before diving into rollback configuration.

How CodeDeploy rollback works

When a rollback triggers, CodeDeploy creates a new deployment entry in the history marked as a rollback. It redeploys the revision from the last successful deployment rather than a new one. The original failed deployment is not deleted; it stays in the deployment history with a failed status.

Two events can trigger an automatic rollback:

• Deployment failure: The deployment itself fails. Instances fail health checks, a lifecycle hook script exits with a non-zero code, or not enough instances become healthy within the timeout window.
• CloudWatch alarm breach: The deployment succeeds, but a CloudWatch alarm fires during or after the deployment window. CodeDeploy stops the deployment and reverses it.

Neither event triggers rollback automatically unless you configure it. Rollback is opt-in.

How to enable automatic rollback

Automatic rollback is configured at the deployment group level. You can set it through the AWS Console or the CLI. The following command enables both rollback triggers for an existing deployment group:

aws deploy update-deployment-group \
  --application-name my-app \
  --current-deployment-group-name my-app-prod \
  --auto-rollback-configuration '{
    "enabled": true,
    "events": [
      "DEPLOYMENT_FAILURE",
      "DEPLOYMENT_STOP_ON_ALARM"
    ]
  }' \
  --alarm-configuration '{
    "enabled": true,
    "alarms": [
      {"name": "my-app-5xx-rate"},
      {"name": "my-app-latency-p99"}
    ]
  }'

The alarm names in alarm-configuration must match alarms that already exist in CloudWatch. If an alarm does not exist or is misspelled, CodeDeploy silently ignores it. Alarms must be added to the deployment group configuration specifically. Adding them to a separate monitoring dashboard does not connect them to rollback.

EC2 vs ECS vs Lambda: rollback comparison

The speed difference matters most during an incident. An ECS or Lambda rollback completes before most users notice. An EC2 rollback may take long enough that you want to post a status update before it finishes.

EC2 rollbacks in detail

When CodeDeploy rolls back an EC2 deployment, it re-runs the last successful revision on the affected instances. The full AppSpec lifecycle runs again: BeforeInstall, Install, AfterInstall, ApplicationStart, and ValidateService, but with the previous revision’s artifacts.

Rollback time on EC2 depends on the number of instances, the deployment configuration (AllAtOnce, HalfAtATime, OneAtATime), and how long your lifecycle hook scripts take. Timing varies significantly by application; treat any published estimate as a rough approximation for your specific workload.

# Manually stop a deployment and trigger rollback
aws deploy stop-deployment \
  --deployment-id d-XXXXXXXXX \
  --auto-rollback-enabled

# Or manually redeploy the last good revision
aws deploy create-deployment \
  --application-name my-app \
  --deployment-group-name my-app-prod \
  --deployment-config-name CodeDeployDefault.OneAtATime \
  --revision '{
    "revisionType": "S3",
    "s3Location": {
      "bucket": "my-deploy-bucket",
      "key": "revisions/last-good-revision.zip",
      "bundleType": "zip"
    }
  }'

After a rollback, the deployment list shows a new entry marked as a rollback with a reference to the original failed deployment. This audit trail is useful when reviewing what happened during an incident.

ECS rollbacks in detail

ECS rollbacks work because CodeDeploy never terminates the original task set (the blue environment) during the deployment. It creates a new task set (the green environment), shifts traffic to it, and then waits before terminating the original. During that wait window, a rollback is just a traffic shift back to the original task set.

This is the blue-green deployment model applied to ECS. The original task set stays alive, so reversing is instant. For ECS-specific pipeline setup leading into this deployment model, see CI/CD Pipelines for ECS.

# Manual rollback for an ECS deployment
aws deploy stop-deployment \
  --deployment-id d-XXXXXXXXX \
  --auto-rollback-enabled

The terminateBlueInstancesOnDeploymentSuccess setting controls when the original task set is terminated after a successful traffic shift:

{
  "blueGreenDeploymentConfiguration": {
    "terminateBlueInstancesOnDeploymentSuccess": {
      "action": "TERMINATE",
      "terminationWaitTimeInMinutes": 15
    }
  }
}

With a 15-minute wait, the original task set stays alive for 15 minutes after traffic shifts to the new version. During that window, CodeDeploy can roll back instantly if a CloudWatch alarm fires. After 15 minutes, the original task set terminates and the instant rollback window closes.

Choose a wait time that gives your monitoring enough time to detect problems. Ten to fifteen minutes is a common starting point. Services with faster alarm detection can use shorter windows.

Lambda rollbacks in detail

Lambda functions have versions and aliases. A version is an immutable snapshot of the function code and configuration. An alias is a pointer to a specific version. When CodeDeploy deploys a Lambda function, it publishes a new version and shifts the alias (such as production) to point to it.

A rollback is CodeDeploy updating that alias to point back to the previous version. Since the previous version is already stored in Lambda and never changes, the rollback is near-instant.

# Check which version the alias currently points to
aws lambda get-alias \
  --function-name my-function \
  --name production

# Manual rollback: point the alias back to the previous version
aws lambda update-alias \
  --function-name my-function \
  --name production \
  --function-version 47

After a rollback, the alias points to the old version. The new version still exists in Lambda but receives no traffic through the alias. You can delete it later, though this is rarely necessary.

For Lambda, CloudWatch alarms are especially important since there are no instances or health checks to fail. See Monitoring Lambda for how to set up function-level error rate and duration alarms that can feed into CodeDeploy rollback.

When to use rollback vs roll forward

Roll forward means shipping a new version with the bug fixed instead of reverting to the old one. Teams that prefer roll forward argue that it keeps the version in production predictable: it is always the latest one. Rollback-first teams argue that reverting is faster when the fix is not obvious.

Use both. Automatic rollback is the right first response to a broken deployment. It stops user impact quickly. Once the system is stable, diagnose the problem and deploy a fix as a new version. When using canary deployments, you already have a natural rollback point built into the traffic-shift phase, which limits how many users are affected before you decide to roll back or continue.

For a structured approach to deciding between rollback and roll forward during a live incident, Incident Response with Monitoring covers the decision framework.

Database migrations and rollback safety

Rollback is not always safe, and database migrations are the main reason why.

Consider this scenario: your new version adds a user_verified column with a NOT NULL constraint. After deploying, CodeDeploy triggers a rollback to the old version. The old application does not write user_verified. Every insert now fails because the column is required and has no default.

The safe pattern separates schema changes from application changes:

1. Deploy the migration first as a backward-compatible addition (nullable column, a column with a default value, or a new table). The old application still works against the new schema.
2. Deploy the application change that uses the new schema. Both old and new application versions can coexist with the schema.
3. After the application change is fully deployed and stable, tighten the schema constraints if needed.

See Dev vs Staging vs Production for how to sequence and test migration changes across environments before they reach production.

How to test rollback in staging

Most teams find out their rollback is broken during a real incident. Test it in staging on a regular schedule instead.

1. Deploy a version with a deliberately broken endpoint (returning 500 for every request) or injected latency above your alarm threshold.
2. Wait for the CloudWatch alarm to fire.
3. Verify CodeDeploy triggers the rollback automatically.
4. Verify the rollback completes and the alarm returns to OK.
5. Measure the total time from deployment to rollback completion. This is your real MTTR floor.

# Deploy the bad version to staging
aws deploy create-deployment \
  --application-name my-app-staging \
  --deployment-group-name my-app-staging \
  --revision '{
    "revisionType": "S3",
    "s3Location": {
      "bucket": "my-deploy-bucket",
      "key": "staging/intentionally-bad-version.zip",
      "bundleType": "zip"
    }
  }'

# Poll for the rollback deployment to appear
aws deploy list-deployments \
  --application-name my-app-staging \
  --deployment-group-name my-app-staging \
  --query 'deployments[0]' \
  --output text

If the alarm does not fire within a few minutes of deploying the bad version, your thresholds may be too loose. If the rollback does not trigger, check that autoRollbackConfiguration.enabled is true in the deployment group and that the alarm names match exactly. For keeping staging close enough to production to trust the results, see Secure CI/CD Pipelines.