AWS CodeDeploy

What CodeDeploy is

CodeDeploy automates rolling a new version of your app onto your compute, so releases aren’t manual and a bad version can roll back on its own. You tell it what to release and where; it handles the mechanics without you SSH-ing into boxes or hand-editing a load balancer. It works across three compute platforms — EC2/on-premises instances, AWS Lambda, and Amazon ECS — and the platform is the biggest fork in how it behaves. It’s the “deploy” half of a CI/CD setup: something else builds the artifact, and CodeDeploy releases it.

Design Beaver models CodeDeploy as a regional deployment orchestrator, so it validates its deploy targets, its revision source, and the IAM each edge needs as you draw, not after a failed rollout.

When to use CodeDeploy (and when not to)

Reach for CodeDeploy when you want repeatable, automated deployments to EC2 or on-premises hosts instead of hand-running scripts over SSH. It’s also the right tool for a controlled traffic-shift release — a canary or linear blue-green rollout for a Lambda function or ECS service, with automatic rollback wired to CloudWatch alarms. If you’re building a pipeline and want a managed deploy stage rather than scripting the rollout yourself, this is it. And when you need lifecycle hooks (before-install, after-install, validate-service) to run your own pre/post-deploy steps on each host, that’s exactly what the AppSpec file gives you.

Don’t reach for it when the workload is a managed platform that deploys itself from a source repo or image — App Runner, Amplify Hosting, and Elastic Beanstalk each run their own deployments, so there’s no CodeDeploy target to attach. Skip it when you want native, built-in ECS rolling updates and don’t need blue/green traffic shifting — the ECS rolling deployment controller is simpler. Purely static content is an S3 sync plus a CloudFront invalidation, not an application deployment. And if you only need to build and test artifacts, that’s CodeBuild’s job; CodeDeploy consumes build output, it doesn’t produce it.

Variants: three compute platforms, not three sizes

The compute platform is the fundamental choice, set per CodeDeploy application — these are genuinely different deployment mechanics, not sizes of the same thing.

CodeDeploy pricing in plain English

For the cloud platforms, CodeDeploy itself is free — you pay only for the underlying compute and load balancer. On-premises instances are the one metered case.

For an all-AWS setup there’s effectively no CodeDeploy line item, so cost tuning is about the compute and load balancer, not CodeDeploy. If you are seeing meaningful CodeDeploy charges, on-premises update volume is the place to look.

How CodeDeploy connects to other services

CodeDeploy acts through a service role you give it (the AWS-managed AWSCodeDeployRole policy covers the common case), plus, for EC2/on-premises, an instance profile on each target host so the agent can fetch the revision. This is where a picture of boxes and arrows usually hides the real work — the role, the direction, the requirement that makes each edge actually function. Design Beaver models each of these connections, so it knows what CodeDeploy can talk to and what that connection needs to be correct.

• →EC2

  CodeDeploy deploys an application revision to EC2 instances (a single deployment group, an Auto Scaling group, or instances selected by tag), running the AppSpec lifecycle hooks on each host — in-place or blue/green

• →Lambda

  CodeDeploy performs a blue/green release of a Lambda function, shifting traffic from the current version to a new version behind a weighted alias (canary, linear, or all-at-once)

• →ECS

  CodeDeploy runs a blue/green deployment of an ECS service — it creates a replacement (green) task set from the new task definition and shifts load-balancer traffic to it incrementally

• →Application Load Balancer

  A blue/green (or load-balanced in-place) deployment uses an Application Load Balancer to swing production traffic between the old and new environment — CodeDeploy re-points the listener/target group so users move to the new version with no dropped requests

• →S3

  For EC2/on-premises deployments, CodeDeploy pulls the application revision — the AppSpec file plus your app content, zipped into a bundle — from an S3 bucket; the CodeDeploy agent on each instance downloads it from S3 at deploy time

• →SNS

  CodeDeploy sends deployment and instance lifecycle notifications (started, succeeded, failed, rolled back, etc.) to an SNS topic via a deployment-group trigger, so a team can fan those events out to email, chat, or a Lambda

• →EventBridge

  CodeDeploy emits deployment- and instance-state-change events that EventBridge can match on, letting you trigger downstream automation (a Lambda, a Step Functions workflow, another notification) when a deployment reaches a given state

• ←CodePipeline

  CodePipeline invokes CodeDeploy as the Deploy stage of a pipeline — the pipeline hands CodeDeploy the built artifact (from its S3 artifact store) and CodeDeploy releases it to the EC2/Lambda/ECS target

What CodeDeploy can’t connect to

Some edges look reasonable on a canvas but don’t exist in AWS. Design Beaver flags them instead of letting you draw a diagram that can’t be built.

• ✕App Runner

  CodeDeploy cannot deploy to App Runner. App Runner is a fully managed platform that runs its own deployments — it redeploys automatically from a source container image (ECR) or connected code repository — and exposes no CodeDeploy target (no agent, no deployment group, no task-set/listener model). CodeDeploy's targets are only EC2/on-premises instances, Lambda functions, and ECS services.

• ✕CodeCommit

  CodeDeploy does not pull an application revision from CodeCommit. Its revision repositories are Amazon S3 or GitHub only (for the EC2/on-premises platform); a Git source in CodeCommit reaches CodeDeploy indirectly through a pipeline (CodePipeline builds/packages the source and hands CodeDeploy an S3 artifact), not as a direct CodeDeploy source.

Anti-patterns Design Beaver catches

These are the CodeDeploy mistakes that pass a diagram review but break under load — the ones the validation engine flags as you draw.

Gotchas that bite in production

• No alarm gate means a bad release goes to 100%. CodeDeploy only fails a deployment on the hook or health failures it’s told to watch. A version that’s up but throwing 5xx errors will finish its traffic shift unless a CloudWatch alarm is wired to the deployment group with automatic rollback enabled. This is the single most important thing to configure for blue/green.
• The agent is the usual culprit. For EC2/on-premises, hosts without a healthy, current CodeDeploy agent silently drop out of the deployment or fail it. A stale agent version is a classic cause of “worked on some instances, not others.” Auto-update the agent and confirm its health before relying on the fleet.
• CodeDeploy shifts traffic; it doesn’t publish code for Lambda or ECS. It moves traffic to an already-published version or an already-registered task definition. Wire it up without a preceding build/publish step and it deploys nothing new.
• Blue/green needs headroom. Two full environments (or task sets) run at once during the deployment, so plan for the extra capacity. For the Auto Scaling group case, make sure your launch template produces a working instance on its own, since CodeDeploy copies the group to build the replacement.
• Don’t hand-edit the load balancer mid-deployment. CodeDeploy drives target registration and listener rules during a blue/green cutover. Changing them yourself while a deployment runs can strand traffic on the wrong target group.
• It deploys; it doesn’t build. Getting an artifact ready is CodeBuild, SAM, or CloudFormation; CodeDeploy takes it from there. Draw the build-to-deploy handoff through CodePipeline (or a shared S3 artifact bucket), not as a build-tool-to-CodeDeploy line.

Further reading

• Official AWS documentation