/aws-deployment

CodeDeploy

Deployment Strategy Comparison

Recommendation: Blue/green for production EC2. Canary for ECS/Lambda production where you need a validation window.

EC2/On-Premises

appspec.yml

version: 0.0
os: linux
files:
  - source: /
    destination: /opt/myapp
    overwrite: true
permissions:
  - object: /opt/myapp/bin
    pattern: "*.sh"
    owner: appuser
    mode: 755
    type:
      - file
hooks:
  ApplicationStop:
    - location: scripts/stop.sh
      timeout: 120
      runas: appuser
  BeforeInstall:
    - location: scripts/before_install.sh
      timeout: 300
  AfterInstall:
    - location: scripts/after_install.sh
      timeout: 300
  ApplicationStart:
    - location: scripts/start.sh
      timeout: 120
  ValidateService:
    - location: scripts/validate.sh
      timeout: 300

EC2 Lifecycle Hooks (Ordered)

In-place deployment:

1. ApplicationStop — Runs PREVIOUS revision's stop script
2. DownloadBundle — Agent-only; downloads revision
3. BeforeInstall — Setup tasks (create dirs, decrypt)
4. Install — Agent-only; copies files per files section
5. AfterInstall — Post-install config (permissions, config generation)
6. ApplicationStart — Start services
7. ValidateService — Health checks, smoke tests

Additional hooks when a load balancer is configured (both in-place and blue/green):

1. BeforeBlockTraffic — Pre-deregistration on original instances
2. BlockTraffic — Agent-only; deregisters from ELB
3. AfterBlockTraffic — Cleanup on original instances
4. (Standard hooks 1-7 on replacement instances)
5. BeforeAllowTraffic — Pre-registration on replacement instances
6. AllowTraffic — Agent-only; registers with ELB
7. AfterAllowTraffic — Post-registration validation

EC2 Deployment Configurations

EC2 Pitfalls

ApplicationStop uses PREVIOUS revision's scripts: Broken stop scripts block ALL future deployments. Fix: deploy a revision that only fixes the stop script, or remove /opt/codedeploy-agent/deployment-root/ on affected instances and restart agent.

file_exists_behavior unset: Redeploys fail with "file already exists." Always set in CreateDeployment: OVERWRITE, RETAIN, or DISALLOW.

Auto Scaling loop: Failed deployments on new instances cause infinite provision-terminate cycle. Fix: suspend Launch on ASG, fix deployment, resume.

MinimumHealthyHosts miscalculation: Setting 90% on 3 instances = 2.7 rounded to 3 — deployment can never proceed. Ensure at least one instance can be taken offline.

ECS (Blue/Green)

ECS deployments always use blue/green. CodeDeploy creates a replacement task set, optionally routes test traffic, then shifts production traffic.

appspec.yml (ECS)

version: 0.0
Resources:
  - TargetService:
      Type: AWS::ECS::Service
      Properties:
        TaskDefinition: "arn:aws:ecs:REGION:ACCOUNT:task-definition/my-task:3"
        LoadBalancerInfo:
          ContainerName: "my-container"
          ContainerPort: 8080
        PlatformVersion: "LATEST"
Hooks:
  - BeforeInstall: "arn:aws:lambda:REGION:ACCOUNT:function:BeforeInstallHook"
  - AfterInstall: "arn:aws:lambda:REGION:ACCOUNT:function:AfterInstallHook"
  - AfterAllowTestTraffic: "arn:aws:lambda:REGION:ACCOUNT:function:TestTrafficHook"
  - BeforeAllowTraffic: "arn:aws:lambda:REGION:ACCOUNT:function:BeforeTrafficHook"
  - AfterAllowTraffic: "arn:aws:lambda:REGION:ACCOUNT:function:AfterTrafficHook"

ECS Lifecycle Hooks (Ordered)

1. BeforeInstall — Lambda (scriptable)
2. Install — Agent-only; creates replacement task set, waits for stability
3. AfterInstall — Lambda (scriptable); validate replacement task set
4. AllowTestTraffic — Agent-only; routes test listener to replacement target group
5. AfterAllowTestTraffic — Lambda (scriptable); test via test traffic port
6. BeforeAllowTraffic — Lambda (scriptable); pre-cutover gate
7. AllowTraffic — Agent-only; shifts production traffic per config
8. AfterAllowTraffic — Lambda (scriptable); post-cutover validation

Scriptable hooks: BeforeInstall, AfterInstall, AfterAllowTestTraffic, BeforeAllowTraffic, AfterAllowTraffic. All invoke Lambda functions (not shell scripts).

ECS Deployment Configurations

ECS Pitfalls

Lifecycle hook 1-hour timeout: CodeDeploy waits up to 3600s for the PutLifecycleEventHookExecutionStatus callback. This is the CodeDeploy hook timeout, not the Lambda execution timeout (which is max 900s). If the Lambda doesn't call back within 1 hour, the hook fails.

Test listener required for AfterAllowTestTraffic: Without a test listener on the ALB, this hook is skipped — no pre-production validation window.

Original task set termination: Configure terminationWaitTimeInMinutes on deployment group. Default is 0 — original tasks terminated immediately after shift (no manual rollback window).

Lambda

Traffic shifts between two function versions using an alias.

appspec.yml (Lambda)

version: 0.0
Resources:
  - MyFunction:
      Type: AWS::Lambda::Function
      Properties:
        Name: "my-function"
        Alias: "live"
        CurrentVersion: "1"
        TargetVersion: "2"
Hooks:
  - BeforeAllowTraffic: "arn:aws:lambda:REGION:ACCOUNT:function:PreTrafficHook"
  - AfterAllowTraffic: "arn:aws:lambda:REGION:ACCOUNT:function:PostTrafficHook"

Lambda Lifecycle Hooks

1. BeforeAllowTraffic — Validate new version (invoke directly, run tests)
2. AllowTraffic — Agent-only; shifts alias traffic per config
3. AfterAllowTraffic — Validate production behavior post-shift

Lambda Deployment Configurations

Rollback Configuration

aws deploy update-deployment-group \
  --application-name MyApp \
  --deployment-group-name MyDG \
  --auto-rollback-configuration enabled=true,events=DEPLOYMENT_FAILURE,DEPLOYMENT_STOP_ON_ALARM

ECS/Lambda: rollback re-routes traffic to original task set/version. EC2: rollback creates a NEW deployment with last known good revision.

Manual rollback: aws deploy stop-deployment --deployment-id ID --auto-rollback-enabled

Recommendation: Always enable DEPLOYMENT_STOP_ON_ALARM with error rate + latency alarms for production.

Creating Deployment Groups

EC2 Deployment Group

aws deploy create-deployment-group \
  --application-name MyApp \
  --deployment-group-name MyDG \
  --deployment-config-name CodeDeployDefault.OneAtATime \
  --ec2-tag-filters Key=Environment,Value=MyEnvironment,Type=KEY_AND_VALUE \
  --service-role-arn arn:aws:iam::ACCOUNT:role/CodeDeployServiceRole \
  --auto-rollback-configuration enabled=true,events=DEPLOYMENT_FAILURE,DEPLOYMENT_STOP_ON_ALARM

ECS Deployment Group

aws deploy create-deployment-group \
  --application-name MyECSApp \
  --deployment-group-name MyECSDG \
  --deployment-config-name CodeDeployDefault.ECSCanary10Percent5Minutes \
  --service-role-arn arn:aws:iam::ACCOUNT:role/CodeDeployECSRole \
  --ecs-services serviceName=my-service,clusterName=my-cluster \
  --load-balancer-info "targetGroupPairInfoList=[{targetGroups=[{name=tg-blue},{name=tg-green}],prodTrafficRoute={listenerArns=[ALB_LISTENER_ARN]},testTrafficRoute={listenerArns=[TEST_LISTENER_ARN]}}]"

Common Errors

Security

• Scope CodeDeploy service role to specific deployment groups and S3 artifact paths
• Encrypt deployment artifacts in S3 (SSE-KMS recommended)
• Enable CloudTrail for codedeploy:* API auditing
• MUST NOT log secrets in appspec hook scripts (stdout is captured in deployment logs)
• Encrypt CloudWatch Logs groups for CodeDeploy event logs with KMS
• Configure CloudWatch alarms on error rate/latency metrics for use with DEPLOYMENT_STOP_ON_ALARM
• See CodeDeploy security best practices

Related

• codepipeline.md for CodeDeploy action in pipelines
• troubleshooting.md for additional error patterns