The Deployment-Day Runbook

A short, boring checklist beats heroics. Here's the pre-flight, launch, and post-deploy routine that keeps release day calm.

Great deploys are boring deploys. The difference between a calm release and a scramble is almost never talent — it's a runbook: a shared checklist that turns tribal knowledge into steps anyone on the team can follow, especially the person on call at 2 a.m.

Before you ship (pre-flight)

  • CI green on the exact commit; the artifact is built, scanned, and tagged by SHA.
  • Migrations are backward-compatible — the old and new versions both run against the new schema (expand/contract).
  • Rollback target identified: the previous known-good image/version is one command away.
  • Dashboards open, alarms armed, on-call aware. Deploy in a low-traffic window if you can.

During the rollout

  • Ship via canary or blue/green; watch error rate and p99 through the bake window.
  • Smoke-test the critical path (login, checkout) on the new version before full traffic.

After it's live

  • Confirm metrics are steady for 15–30 minutes before calling it done.
  • Tag the release, update the changelog, and note anything surprising for the next deploy.

Decouple deploy from release

Ship code dark behind a feature flag and turn it on separately. Now "deploy" and "release" are two decisions, and rolling back a feature is a flag flip — not a redeploy.

Example

Example · yaml
# release-runbook.yml — a living checklist, versioned with the app
release: myapp v42 (commit 9f3c1a2)
window: 2026-07-15 14:00 UTC (low traffic)

pre_flight:
  - ci_green_on_commit: true
  - image_tagged_by_sha: myapp:9f3c1a2
  - db_migration_backward_compatible: true
  - rollback_target: myapp:41 (previous prod)
  - dashboards_open: [alb-5xx, p99-latency, ecs-cpu]

rollout:
  strategy: canary   # 10% for 5 min, then linear
  smoke_tests: ["GET /healthz => 200", "login flow", "checkout flow"]
  abort_if: "5xx alarm OR p99 > 800ms"

rollback_command: >
  aws ecs update-service --cluster myapp-prod --service web
  --task-definition myapp:41 --force-new-deployment

post_deploy:
  - watch_metrics_minutes: 30
  - tag_release: git tag -a v42 -m 'prod release'
  - update_changelog: true

When to use it

  • An ops engineer follows the pre-flight checklist before every production deploy, catching a missing SSM parameter before it causes a failed startup.
  • A team uses a shared deployment runbook so any engineer can drive a release, not just the one who originally built the service.
  • A post-incident review shows that following the rollback section of the runbook reduced the mean time to restore from 45 minutes to 8 minutes.

More examples

Pre-deploy health snapshot script

Captures the current task count and ALB target health before touching anything, so you have a baseline to compare against after deploy.

Example · bash
#!/bin/bash
# Pre-flight: capture baseline metrics before deploy
echo '=== Pre-Deploy Snapshot ==='
echo 'Running tasks:'
aws ecs describe-services --cluster prod --services myapp \
  --query 'services[0].[runningCount,pendingCount,taskDefinition]' --output table

echo 'ALB target health:'
aws elbv2 describe-target-health \
  --target-group-arn $TG_ARN \
  --query 'TargetHealthDescriptions[*].[Target.Id,TargetHealth.State]' --output table

Trigger deploy and monitor progress

The core deploy step: trigger the ECS service update and block until ECS confirms all tasks are stable.

Example · bash
echo '=== Starting Deploy ==='
aws ecs update-service \
  --cluster prod \
  --service myapp \
  --task-definition myapp:$NEW_VERSION \
  --force-new-deployment

echo 'Waiting for service stability...'
aws ecs wait services-stable --cluster prod --services myapp
echo 'Deploy complete'

Post-deploy verification checklist

Hits the health endpoint and checks the state of key alarms immediately after deploy to confirm the new version is serving correctly.

Example · bash
#!/bin/bash
# Post-deploy checks
HTTP=$(curl -s -o /dev/null -w '%{http_code}' https://api.example.com/health)
echo "Health endpoint: $HTTP"

aws cloudwatch describe-alarms \
  --alarm-names myapp-5xx-high myapp-high-cpu \
  --query 'MetricAlarms[*].[AlarmName,StateValue]' \
  --output table

echo 'Check done — review alarms above'

Related

deploy pro auto rollbackdeploy security checklistdeploy pro zero downtime

Discussion

  • Be the first to comment on this lesson.
The Deployment-Day Runbook — AWS Deployment | SoundsCode