AWS CodeDeploy: AI-Optimized Technical Reference

Service Overview

AWS CodeDeploy automates software deployments across EC2, Lambda, and ECS platforms. Eliminates manual SSH deployments but introduces AWS-specific complexity and failure modes.

Deployment Platforms & Capabilities

EC2 and On-Premises

• Agent-based: CodeDeploy agent runs on target servers
• Critical Failure Mode: Agent randomly stops responding - check /var/log/aws/codedeploy-agent/ and restart service
• Network Requirements: Outbound HTTPS access to AWS APIs required
• Ubuntu 20.04 Issue: Agent installation fails without Python 2.7 - cryptic error: ERROR: Could not find a version that satisfies the requirement botocore

Lambda Functions

• Traffic Shifting: Canary deployments work reliably (unlike custom implementations)
• Performance: Deployment process is functional but AWS-controlled timing

ECS Containers

• Blue/Green Strategy: Functional but slow due to ECS performance limitations
• Process: New containers → traffic shift → old container termination

Cost Structure

Deployment Type	Cost	Hidden Costs
EC2	Free	None
On-Premises	$0.02/instance/deployment	Scales rapidly (1000 servers × 2 weekly = $40/week)
Blue/Green	Free service	2x infrastructure costs during deployment

Real-World Cost Example

• 30-minute deploy on 10 large instances: $10-15 additional EC2 charges
• Blue/Green temporarily doubles all instance costs

Critical Configuration: AppSpec File

Lifecycle Phases (Execution Order)

1. ApplicationStop - Terminates application
2. BeforeInstall - Pre-installation scripts
3. Install - File copying
4. AfterInstall - Post-installation (migrations, permissions)
5. ApplicationStart - Application startup
6. ValidateService - Health checks

Most Common Failure Point

ValidateService phase - 70% of deployment failures occur here due to:

• Incorrect health check scripts
• Insufficient timeout values (default: 300 seconds per lifecycle event)
• Wrong file permissions

Production-Ready AppSpec Template

version: 0.0
os: linux
files:
  - source: /
    destination: /var/www/html
hooks:
  BeforeInstall:
    - location: scripts/install_dependencies.sh
      timeout: 300
      runas: root
  ApplicationStart:
    - location: scripts/start_server.sh
      timeout: 60
      runas: root
  ValidateService:
    - location: scripts/health_check.sh
      timeout: 30

Blue/Green Deployment Reality

Traffic Shifting Options

Strategy	Behavior	Use Case	Risk Level
Canary	10% traffic for 5 minutes, then 100%	Production safety	Low - catches issues before full deployment
Linear	10% increments every 10 minutes	Paranoid deployments	Lowest - fine-grained control
All-at-once	Immediate 100% traffic shift	High confidence deployments	High - YOLO mode

Automatic Rollback Limitations

• Detection Time: 5-10 minutes typical, up to 1 hour maximum per lifecycle event
• Success Rate: ~70% reliable rollback execution
• Real Failure Example: E-commerce checkout broke during Black Friday, 8-minute detection window, $30K lost sales
• Critical Limitation: Health checks depend on load balancer configuration

Critical Failure Modes & Solutions

1. IAM Permissions (Primary Failure Cause)

Symptom: Deployment stuck in "Pending" status for hours
Root Cause: Service role vs. instance role permission conflicts
Cost Impact: $200+ in duplicated blue/green infrastructure during troubleshooting
Solution: Verify CodeDeploy service role AND EC2 instance profile permissions separately

2. Agent Connectivity Issues

Symptom: Silent deployment failures
Diagnosis: Check security groups and NACLs for outbound HTTPS
Log Location: /var/log/aws/codedeploy-agent/codedeploy-agent.log
Common Error: ERROR [codedeploy-agent(31743)]: Cannot reach InstanceService

3. File Permissions

Symptom: Deployment fails after file copy
Root Cause: Agent runs as root, application runs as different user
Solution: Use chown/chmod in AfterInstall hooks

4. YAML Syntax Errors

Impact: 3am debugging sessions for indentation issues
Prevention: YAML validation in CI/CD pipeline

Service Limits (Production Impact)

Limit	Value	Real-World Impact
Applications per region	1,000	Never reached
Deployment groups per application	1,000	Rarely reached
Concurrent deployments per account	1,300	Sufficient for most use cases
Concurrent deployments per group	1	Blocks simultaneous deployments

Critical Bottleneck: The "1 per deployment group" limit prevents parallel deployments of same application.

Integration Complexity

CI/CD Tool Compatibility

• Jenkins: Plugin works 85% of time
• GitHub Actions: Requires custom scripting, solid once configured
• GitLab CI/CD: Manual setup, 3-day configuration typical
• Azure DevOps: Optimized for Azure, AWS integration poor

AWS CLI Integration

aws deploy create-deployment --application-name myapp --deployment-group-name prod --s3-location bucket=mybucket,key=myapp.zip,bundleType=zip

Auto Scaling Integration

Behavior

• New instances automatically receive latest deployment
• Failed deployments trigger instance termination and retry
• Critical Issue: Bad deployments create infinite launch/kill loops

S3 Storage Considerations

• Versioned S3 buckets work reliably
• Eventual Consistency Risk: Wait seconds between upload and deployment to avoid deploying old versions

Troubleshooting Decision Tree

1. Deployment Stuck: Check agent status → verify IAM → check connectivity
2. Generic Errors: CloudWatch logs → instance logs at /var/log/aws/codedeploy-agent/ → AppSpec syntax → permissions
3. Rollback Failures: Manual rollback required → create new deployment with previous revision
4. "Stop and Rollback" Button: 60% success rate, useless after ApplicationStart phase

Competitive Analysis: When CodeDeploy Makes Sense

Choose CodeDeploy When:

• Heavy AWS integration required
• Blue/green deployments needed out-of-box
• Team already familiar with AWS IAM complexity
• Budget allows for infrastructure duplication costs

Avoid CodeDeploy When:

• Multi-cloud deployments required
• Team lacks AWS expertise
• Budget constraints prevent blue/green costs
• Simple deployment needs don't justify complexity

Resource Requirements

Time Investment

• Initial Setup: 1-2 days for basic configuration
• IAM Troubleshooting: 6+ hours typical for permission issues
• Production Readiness: 1-2 weeks including testing and monitoring setup

Expertise Requirements

• Mandatory: AWS IAM understanding
• Recommended: YAML, bash scripting, AWS networking
• Critical: CloudWatch log analysis for troubleshooting

Migration Considerations

Breaking Changes

• Agent updates occasionally break compatibility
• AppSpec format changes require deployment bundle updates
• IAM policy changes affect existing deployments

Operational Intelligence

• Default timeouts will fail in production - always customize
• Health check configuration is more critical than documentation suggests
• Blue/green cost doubling often surprises finance teams
• Manual rollback capability is essential backup plan